Ir al contenido

Python and .venv Configuration in VS Code

Troubleshooting interpreters and virtual environments using VS Code on Windows systems.

0views

This guide provides the definitive technical procedure for diagnosing, configuring, and implementing Python development environments in Visual Studio Code on Windows systems. It covers everything from the correct assignment of global interpreters (including non-standard paths from winget or Microsoft Store) to the automation and installation of dependencies in isolated environments (.venv).


To ensure a predictable development environment, it is fundamental to separate the user interface from the execution engine and the dependency packages of each project.

  • Visual Studio Code (UI/Editor): It functions strictly as an advanced text editor and integrated development environment. It does not include a built-in Python engine; instead, it delegates code execution to an external interpreter.
  • Python Engine (python.exe): It is the binary responsible for processing and interpreting code instructions. It runs directly on the system or within sub-environments.

Global Environment vs. Virtual Environment (.venv)

Sección titulada «Entorno Global vs. Entorno Virtual (.venv)»
  • Global Python: Corresponds to the system's base installation. It acts as the initial template and should not be modified with external packages to avoid dependency collisions between different projects.
  • Virtual Environments (.venv): They are isolated subdirectories that encapsulate their own Python binary and their dependency tree (site-packages).
┌──────────────────────────────────────────────────────────┐
│                   Sistema Operativo                      │
│   (Python Global - Instalación base libre de paquetes)   │
└────────────────────────────┬─────────────────────────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
   ┌────────────────────┐        ┌────────────────────┐
   │    Proyecto A      │        │    Proyecto B      │
   │  (.venv A - Aislado)│        │  (.venv B - Aislado)│
   │  - Pandas v1.0     │        │  - Pandas v2.0     │
   │  - Requests        │        │  - Gemini API      │
   └────────────────────┘        └────────────────────┘

Strictly follow the following order to ensure that your workspace initializes and executes Python without dependency failures.

  1. Access the Extensions tab in VS Code (Ctrl + Shift + X).
  2. Search for the official Python extension developed by Microsoft.
  3. Press Install. This extension enables debugging, IntelliSense, and dynamic interpreter management capabilities in the editor.

Step 2: Locating the Global Interpreter (Cases of winget)

Sección titulada «Paso 2: Localización del Intérprete Global (Casos de winget)»

When Python is installed through package managers such as winget or the Microsoft Store, it is common for the installer not to register the executable in the standard system paths (PATH). To locate its base executable:

  1. Open a command terminal on your system (CMD or PowerShell).
  2. Run the following search command:
Ventana de terminal
where.exe python
  1. The terminal will return the absolute path to the active executable. For example: C:\Program Files\Python312\python.exe or C:\Users\<Usuario>\AppData\Local\Microsoft\WindowsApps\python.exe. Save this path.

Step 3: Virtual Environment Initialization (.venv)

Sección titulada «Paso 3: Inicialización del Entorno Virtual (.venv)»

To avoid failures or blocking dialog windows in the integrated VS Code menus, create the environment directly from the editor's terminal:

  1. Open an integrated terminal in VS Code (Ctrl + Ñ or Ctrl + ~).
  2. Run the standard virtual environment module pointing to the directory name .venv:
Ventana de terminal
python -m venv .venv
  1. Upon completion of the execution, a new directory .venv will be created in the root of your workspace.

Step 4: Linking the VS Code Interpreter with the Virtual Environment

Sección titulada «Paso 4: Vinculación del Intérprete de VS Code con el Entorno Virtual»

Creating the subdirectory .venv does not activate the connection in the editor. You must force VS Code to use the newly created interpreter:

  1. Ensure you have at least a file with the .py extension open and selected in the VS Code editor (this activates the Python contextual engine).
  2. Open the Command Palette using Ctrl + Shift + P.
  3. Type and select Python: Select Interpreter (Python: Select Interpreter).
  4. The editor will present a list. Select the option that points directly to your local environment. It is usually indicated as recommended:
Ventana de terminal
Python 3.x.x ('.venv': venv) ./.venv/Scripts/python.exe
  1. Status Verification: Observe the bottom right corner of the VS Code status bar.
    • ✕ Incorrect Path: Shows Python 3.x.x (you are using the global system binary).
    • ✓ Correct Path: Shows Python 3.x.x ('.venv') (the environment is correctly linked).

Once the interpreter is linked in the editor, each new terminal opened will automatically inherit the active virtual environment.

  1. Open a new integrated terminal (Ctrl + Ñ).
  2. Validate that the command prompt shows the activation prefix on the far left:
Ventana de terminal
(.venv) PS C:\MiProyecto>
  1. Install the necessary project libraries directly within your isolated environment:
Ventana de terminal
pip install google-generativeai requests pandas

SymptomRoot CauseSolution
The integrated Create Environment menu requests manual path entry and freezes.VS Code does not automatically locate the base Python installation in the system's PATH (common in installations via winget).Cancel the integrated dialog. Follow Step 3 of this guide to create the environment manually via terminal using python -m venv .venv.
Error ModuleNotFoundError: No module named '<libreria>' when pressing ‘Play’.The code is being executed by an interpreter different from the one containing the installed packages (usually the global one).1. Check the bottom-right bar of VS Code to confirm that the ('.venv') sub-interpreter is linked.
2. If not, repeat Step 4 (Select Interpreter).
The terminal does not show the (.venv) prefix when opened.The current console has not updated after configuring the interpreter or has restricted execution policies in PowerShell.1. Close all active terminals using the trash can icon in the bottom panel.
2. Open a completely new terminal (Ctrl + Ñ). The activation script will run automatically.
The Python version selector does not appear in the VS Code status bar.The editor has not loaded Python contextual services because no code files are open.Open any file with a .py extension in your main editor to force the initialization of the Microsoft extension.