What Python virtual environments are and why you need them, how to create and activate one on Windows, macOS and Linux, managing packages with pip and requirements files, the 'externally managed environment' error, and newer tools.
A virtual environment is a self-contained folder holding a Python interpreter and its own installed packages. It keeps each project's dependencies separate, so upgrading a library for one project doesn't break another, and you never have to install packages into your system Python.
Why bother?
- Different projects can use different versions of the same library.
- You avoid permission problems and conflicts with system tools that depend on Python.
- You can record exact versions so the project works the same on another machine.
Create one
Python includes the venv module. In your project folder:
python3 -m venv .venv # macOS/Linux
py -m venv .venv # WindowsThis creates a .venv folder. The name is a convention; many editors detect it automatically.
Activate it
source .venv/bin/activate # macOS/Linux (bash, zsh)
.venv\Scripts\activate # Windows Command Prompt
.venv\Scripts\Activate.ps1 # Windows PowerShellYour prompt usually shows (.venv). Now python and pip refer to the environment. Type deactivate to leave. If PowerShell blocks the script, you may need to adjust its execution policy for your user; check your organisation's rules first.
You don't have to activate: you can run .venv/bin/python script.py directly, which is handy in scripts and scheduled jobs.
Install packages
python -m pip install requests
python -m pip listUsing python -m pip guarantees you're using the pip that belongs to the active interpreter.
Record and reproduce dependencies
python -m pip freeze > requirements.txt
python -m pip install -r requirements.txtCommit requirements.txt to version control, but add .venv/ to .gitignore: environments aren't portable between machines, so recreate them instead of copying them.
The "externally managed environment" error
On recent versions of Debian, Ubuntu, Fedora and Homebrew Python, running pip install outside a virtual environment may fail with an externally-managed-environment error. This comes from PEP 668: the operating system manages that Python, and pip installs could break system tools. The fix is to create a virtual environment, or use your system package manager or pipx for command-line applications. Avoid overriding the protection.
Choosing a Python version
A venv uses the Python that created it. To use a different version, create the environment with that interpreter, for example python3.13 -m venv .venv, or on Windows py -3.13 -m venv .venv. Check the Python release status page and use a version that still receives security fixes.
Newer tools
- pipx installs command-line tools, each in its own isolated environment.
- uv is a fast, increasingly popular tool that can create environments, install packages and manage Python versions.
- Poetry and PDM manage dependencies and packaging via
pyproject.toml. - conda is common in data science, especially for packages with complex non-Python dependencies.
All build on the same idea. Pick one per project and stick with it.
Troubleshooting
- "command not found: python" on macOS or Linux: use
python3, or activate the environment first. - Packages installed but not found: you probably installed with a different pip. Check
python -m pip --version, which shows the path it belongs to. - The wrong interpreter in your editor: select the
.venvinterpreter explicitly. - A broken environment: it's quicker to delete the
.venvfolder and recreate it than to repair it.
Editor setup
In VS Code, open the Command Palette and choose "Python: Select Interpreter", then pick the .venv interpreter. PyCharm offers to create one for new projects.
Frequently asked questions
Can I move or rename a venv?
Not reliably, as paths are hard-coded. Delete it and recreate it from requirements.txt.
Do I need one for a tiny script?
Not if it uses only the standard library. As soon as you install packages, use one.
Sources and further reading
- Python docs: venv
- Python Packaging User Guide: Installing packages using pip and virtual environments
- PEP 668: Marking Python base environments as externally managed
- Python developer's guide: Status of Python versions
Facts checked on 20 October 2026. Spotted an error? Tell us and we will correct it.