Configure Python Venv in VS Code Integrated Terminal Code Runner

Understanding the Root Cause

The primary reason Code Runner fails to recognize your virtual environment is that it often defaults to the system-wide Python installation or the first available interpreter on your system PATH. When you activate a virtual environment manually in the terminal, your shell session updates the PYTHONPATH and executable locations. However, Code Runner operates independently of the terminal's active state for each execution. It spawns a new process to run your code, which does not inherit the activation context unless explicitly configured.

This disconnect leads to common symptoms such as missing module errors (e.g., ModuleNotFoundError: No module named 'requests') even though you have installed packages in your virtual environment. The solution lies in decoupling the dependency from the terminal session and hardcoding the interpreter location into the editor's configuration. By doing so, every time you press the play button, Code Runner invokes the specific Python binary associated with your project's isolated environment.

Locating Your Virtual Environment Path

Before modifying settings, you need the absolute path to the Python executable within your virtual environment. This path varies depending on your operating system and how you created the venv.

• On Windows: Navigate to your project folder. Inside the virtual environment directory (commonly named venv or .venv), go to Scripts. The executable is typically python.exe.
• On macOS and Linux: Go to your project folder, then into the virtual environment directory, followed by bin. The executable is python3 or python.

For example, if your project is located at /Users/name/myproject and your venv is named myenv, the path would be /Users/name/myproject/myenv/bin/python3. On Windows, it might look like C:\Users\name\myproject\myenv\Scripts\python.exe. Ensure you copy this exact path, as relative paths can sometimes cause resolution issues depending on where VS Code launches the process.

Configuring VS Code Settings

Once you have the correct path, you need to instruct Code Runner to use it. Open VS Code and access the user or workspace settings. It is highly recommended to configure this at the workspace level rather than the user level, ensuring that other projects are not affected by this specific virtual environment configuration.

1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) and select Preferences: Open Workspace Settings (JSON).
2. Add or modify the following entry in the JSON object:

"code-runner.executorMap": {
    "python": "/absolute/path/to/your/venv/bin/python"
}

Replace the placeholder with the actual path you identified in the previous step. For instance:

"code-runner.executorMap": {
    "python": "/Users/jdoe/project/venv/bin/python3"
}

If you are using Windows, remember to escape backslashes or use forward slashes:

"code-runner.executorMap": {
    "python": "C:/Users/jdoe/project/venv/Scripts/python.exe"
}

Save the file. The next time you run a Python script via Code Runner, it will execute using the specified interpreter, granting access to all installed packages within that virtual environment.

Alternative: Using the Default Interpreter Setting

In some cases, simply setting the executor map may not be sufficient if other extensions interfere. A more robust approach involves telling VS Code itself which interpreter to use, which Code Runner often respects if configured correctly. You can set the default Python interpreter for the workspace by selecting the interpreter via the command palette.

Select Python: Select Interpreter from the command palette. Choose the interpreter located in your virtual environment. Once selected, verify that the status bar in the bottom right corner displays the correct path. While Code Runner has its own executorMap, aligning the general VS Code Python context helps prevent conflicts with IntelliSense and debugging tools. If you encounter issues where the change doesn't take effect immediately, restart the VS Code window to clear any cached states.

Troubleshooting Common Issues

If you have configured the path but still face errors, consider the following checks. First, verify that the path is correct by opening a terminal in VS Code and running which python (macOS/Linux) or where python (Windows) to see if it matches your configured path. Second, ensure that no other settings in settings.json are overriding the executor map. Look for keys like code-runner.runInTerminal; setting this to true forces Code Runner to run in the integrated terminal, which might pick up the activated environment if you manually activate it before running, but this is less reliable than the direct path method.

Additionally, check for syntax errors in your settings.json file. A missing comma or an unclosed bracket will cause VS Code to ignore the entire file, reverting to defaults. You can validate the JSON structure by hovering over the error indicator in the editor. If you recently updated VS Code or the Code Runner extension, ensure that your configuration syntax is compatible with the current version, as older configurations might use deprecated keys.

For related issues regarding kernel selection in newer VS Code versions, you may find helpful insights in our guide on Fixing 'Select Kernel' Problem in VS Code, although this primarily affects Jupyter notebooks, the underlying interpreter selection logic shares similarities.

Frequently Asked Questions

Why do I get ModuleNotFoundError after configuring the venv?

This usually means the path in your settings is incorrect or points to a different Python installation. Verify that the packages are actually installed in the target virtual environment by activating it manually and running pip list. Ensure the path in settings.json matches the Python binary of that specific environment exactly.

Can I use a relative path instead of an absolute path?

While possible, relative paths are risky because Code Runner may launch from different working directories depending on the file opened. Absolute paths guarantee consistency across all files in your project. If you must use relative paths, ensure they are resolved from the workspace root, but absolute paths are strongly recommended for stability.

Does this configuration affect debugging?

No, configuring Code Runner's executor map does not automatically update the Python debugger configuration. Debugging uses separate settings defined in launch.json. You should configure your debugger to use the same virtual environment interpreter to ensure breakpoints and variable inspection work correctly within the isolated environment.

What if I switch virtual environments frequently?

You will need to update the settings.json file each time you switch environments. Alternatively, you can use VS Code's built-in interpreter selector (Python: Select Interpreter) and ensure Code Runner is configured to respect the workspace interpreter, though manual executorMap updates remain the most reliable method for Code Runner specifically.

Is there a way to avoid editing settings.json manually?

You can edit settings via the GUI by searching for code-runner.executorMap in the Settings tab. However, the GUI interface for complex maps like executorMap can be cumbersome. Editing the JSON file directly provides better visibility and control over the exact string values being passed to the runner.