How to Create a Python Virtual Environment in VS Code (Windows, macOS, Linux)

Short answer: open your project folder in VS Code, open the terminal (Terminal → New Terminal) and run:

python -m venv .venv

Then activate it (.venv\Scripts\Activate.ps1 on Windows, source .venv/bin/activate on macOS and Linux), press Ctrl+Shift+P, run Python: Select Interpreter and pick the one inside .venv. That's it: VS Code now uses this environment for running, debugging and new terminals.

The rest of this guide covers each operating system and the errors you're most likely to hit, including the PowerShell one that stops almost everyone on Windows.

Why use a virtual environment at all?

Without one, every pip install goes into your system-wide Python. Two projects that need different versions of the same library will eventually break each other. A virtual environment is just a folder (.venv) with its own Python and its own packages, one per project.

Windows

In the VS Code terminal (PowerShell by default):

py -m venv .venv
.venv\Scripts\Activate.ps1

py is the Python launcher that ships with the official installer; python -m venv .venv works too if python is on your PATH. When activation works, your prompt starts with (.venv).

If you use Command Prompt instead of PowerShell, activate with .venv\Scripts\activate.bat.

macOS and Linux

python3 -m venv .venv
source .venv/bin/activate

On Debian and Ubuntu, if you get ensurepip is not available, install the venv module first:

sudo apt install python3-venv

Select the interpreter in VS Code

Activating in the terminal isn't enough on its own; VS Code also needs to know which Python to use for running and debugging.

Press Ctrl+Shift+P (Cmd+Shift+P on macOS).
Run Python: Select Interpreter.
Choose the entry that points into .venv, usually marked as recommended.

From then on, new terminals in this project activate the environment automatically. If you have the Python extension installed, Python: Create Environment in the same command palette does the creation and selection in one step.

Common errors and fixes

"running scripts is disabled on this system"

This is the one I hit myself on Windows, while setting up the project behind this website. Activation fails with:

.\.venv\Scripts\Activate.ps1 : File ...\Activate.ps1 cannot be loaded because
running scripts is disabled on this system.
    + CategoryInfo          : SecurityError: (:) [], PSSecurityException
    + FullyQualifiedErrorId : UnauthorizedAccess

Nothing is wrong with your environment. PowerShell's execution policy blocks all scripts by default on Windows, and Activate.ps1 is a script.

Fix for the current window only (safest, nothing changes permanently):

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned
.venv\Scripts\Activate.ps1

-Scope Process applies only to this PowerShell session; close the window and the policy is back to normal. You can also do both in one line, which is what I ended up using:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned; .venv\Scripts\Activate.ps1

Permanent fix for your user (no admin rights needed):

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

RemoteSigned lets local scripts run while still requiring a signature for scripts downloaded from the internet, which is the usual setting for development machines. Don't use Unrestricted just to make the error go away.

VS Code doesn't see the environment

If .venv doesn't show up in Select Interpreter, choose Enter interpreter path and point it at:

Windows: .venv\Scripts\python.exe
macOS / Linux: .venv/bin/python

Also make sure you opened the project folder (File → Open Folder), not a single file; VS Code looks for .venv in the workspace root.

Packages install into the wrong Python

You ran pip install, but your code still can't import the package. Check which Python is actually active:

python -c "import sys; print(sys.executable)"

The path should point inside .venv. If it doesn't, the environment isn't active in this terminal. A habit that avoids this entirely is to always install through the interpreter:

python -m pip install requests

Two small habits

Add .venv/ to your .gitignore. The environment is rebuilt from a requirements file, never committed.
Save your dependencies with python -m pip freeze > requirements.txt, and recreate them anywhere with python -m pip install -r requirements.txt.

To leave the environment, run deactivate.