Python Virtual Environments: Create and Activate a venv

Quick answer

Run these from your project's root folder. .venv is the conventional name: editors detect it automatically and most .gitignore templates already exclude it.

# macOS / Linux
python3 -m venv .venv
source .venv/bin/activate
pip install requests
deactivate

# Windows (PowerShell)
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install requests
deactivate

Why use a virtual environment?

Without one, pip install puts packages into a single global location shared by every project. Sooner or later two projects need different versions of the same library, an upgrade for one breaks the other, and nobody remembers which packages a project actually needs. On recent Linux distributions and Homebrew Python, installing into the system interpreter is now blocked altogether with an externally-managed-environment error (PEP 668), precisely to stop pip from breaking OS tools.

A virtual environment solves this by giving each project its own site-packages folder and its own copies of python and pip. It is cheap (a few megabytes before you install anything), disposable and easy to recreate from a requirements file.

Create a virtual environment with python -m venv

The venv module has shipped with Python since 3.3, so there is nothing to install. On macOS and Linux the command is usually python3; on Windows the py launcher is the most reliable way to call Python. The environment uses whichever Python version created it, so to target a specific version, call that interpreter explicitly.

Useful options: --prompt changes the name shown in your shell prompt, --upgrade-deps upgrades pip in the new environment right away, and --system-site-packages lets the environment see globally installed packages (rarely what you want). On Debian and Ubuntu, venv is split into a separate package; if you see "ensurepip is not available", install python3-venv first.

python3 -m venv .venv
python3.12 -m venv .venv                 # a specific version (macOS / Linux)
py -3.12 -m venv .venv                   # a specific version (Windows)
python3 -m venv .venv --prompt myapp --upgrade-deps

sudo apt install python3-venv            # Debian / Ubuntu, if venv is missing

Activate the virtual environment

Activation adjusts your current shell so that python and pip point to the environment's copies, and adds its name to your prompt, such as (.venv). It only affects the terminal you run it in. The script differs per shell and operating system: on Windows the environment has a Scripts folder, on macOS and Linux a bin folder.

source .venv/bin/activate          # bash / zsh
source .venv/bin/activate.fish     # fish
source .venv/bin/activate.csh      # csh / tcsh

.venv\Scripts\activate.bat

.venv\Scripts\Activate.ps1

# If blocked: allow local scripts for your user (one-time)
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
# Or only for this PowerShell window
Set-ExecutionPolicy -ExecutionPolicy Bypass -Scope Process

source .venv/Scripts/activate

Check it worked, and deactivate

After activating, confirm which interpreter your shell is using; the path should be inside .venv. sys.prefix differs from sys.base_prefix only inside a virtual environment. When you are done, run deactivate to return to the global Python, or simply close the terminal. To delete an environment, deactivate it and remove the .venv folder; nothing else on the system refers to it.

which python            # macOS / Linux  -> /path/to/project/.venv/bin/python
where python            # Windows        -> C:\path\to\project\.venv\Scripts\python.exe
python -c "import sys; print(sys.prefix != sys.base_prefix)"   # True inside a venv

deactivate

Manage dependencies with requirements.txt

With the environment active, pip install puts packages inside it. Record exact versions with pip freeze > requirements.txt and commit that file, never the .venv folder itself. Virtual environments contain absolute paths and platform-specific binaries, so they are not portable between machines or even between folders: if you move or rename the project, delete .venv and recreate it. Anyone cloning the repository rebuilds an identical environment from the requirements file.

pip freeze lists every installed package, including dependencies of dependencies. Some teams keep a short hand-written list of direct dependencies and generate the pinned file with a tool such as pip-tools or uv.

pip install django==5.2 requests
pip freeze > requirements.txt
pip install -r requirements.txt      # on another machine, inside a new venv
pip list --outdated

echo ".venv/" >> .gitignore

Select the venv in VS Code

With the Python extension installed, VS Code usually detects a .venv folder in the workspace and offers to use it. If not, open the Command Palette (Ctrl+Shift+P, or Cmd+Shift+P on macOS), run "Python: Select Interpreter" and pick the entry that points to .venv, or choose "Enter interpreter path" and browse to .venv/bin/python (.venv\Scripts\python.exe on Windows). New integrated terminals then activate the environment automatically, and the run button, debugger, linting and Jupyter notebooks all use it. PyCharm offers the same choice under Settings, Project, Python Interpreter.

virtualenv, conda and uv

venv is enough for most projects, but three alternatives are common and solve slightly different problems.

pip install --user virtualenv
virtualenv .venv
virtualenv -p python3.11 .venv

conda create -n myenv python=3.12
conda activate myenv
conda deactivate
conda env export > environment.yml
conda env create -f environment.yml
conda env list

uv venv                          # creates .venv
uv venv --python 3.12
uv pip install -r requirements.txt

uv init myapp && cd myapp
uv add requests                  # updates pyproject.toml and uv.lock
uv run python main.py            # runs inside the project environment

Common errors and fixes

Most virtual environment problems come down to using a different interpreter than the one you think you are using.

• ModuleNotFoundError after installing a package: the package went into one interpreter and your code runs with another. Activate the venv, or select it in your editor, and run python -m pip install ... so pip and python always match.
• error: externally-managed-environment: you ran pip against the system Python. Create and activate a venv first; do not reach for --break-system-packages.
• "running scripts is disabled on this system": PowerShell's execution policy. Run Set-ExecutionPolicy RemoteSigned -Scope CurrentUser.
• 'python' is not recognized on Windows, or the Microsoft Store opens: use the py launcher, or disable the python.exe App execution aliases in Settings and reinstall Python with "Add to PATH" checked.
• "The virtual environment was not created successfully because ensurepip is not available": install python3-venv (Debian/Ubuntu) and try again.
• The venv broke after moving or renaming the folder, or after upgrading Python: delete .venv and recreate it from requirements.txt.