Python Virtual Environments: A Practical Guide to venv (and Fixing 'externally-managed-environment')
Create, activate and manage Python virtual environments with venv on Windows, macOS and Linux — and fix pip's externally-managed-environment error.
Table of contents
- What a virtual environment actually is
- Step 1: Create a virtual environment
- Step 2: Activate it
- Step 3: Install packages
- Step 4: Record and reproduce dependencies
- Step 5: Keep the environment out of Git
- Fixing "error: externally-managed-environment"
- Using virtual environments with your editor
- Common mistakes and quick fixes
- Beyond venv
If you write Python, you need virtual environments. They keep each project's packages separate, stop version conflicts between projects, and protect your operating system's own Python from accidental breakage. Python includes everything you need in the standard library module venv.
This guide covers creating and activating environments on every major operating system, managing dependencies, using environments with editors, and fixing the common externally-managed-environment error.
What a virtual environment actually is
A virtual environment is a directory containing:
- a
pyvenv.cfgfile that points to the Python installation it was created from, - a
bin/(macOS/Linux) orScripts\(Windows) folder withpython,pipand activation scripts, - its own
site-packagesfolder, where packages you install are placed.
When the environment is active, python and pip refer to the copies inside it, so pip install puts packages into that project only. The mechanism was standardised in PEP 405 and has shipped with Python since version 3.3.
Why you need one
- Project A needs Django 4, Project B needs Django 5. Without isolation, installing one breaks the other.
- Reproducibility. A clean environment plus a requirements file lets a teammate (or a server) recreate exactly what you have.
- System safety. Many operating systems rely on their own Python for system tools. Installing packages into it can break those tools — which is why modern Linux distributions now block it by default (more on that below).
Step 1: Create a virtual environment
Open a terminal in your project folder and run:
macOS / Linux:
python3 -m venv .venv
Windows:
py -m venv .venv
This creates a folder called .venv inside your project. The name is a convention, not a requirement — but .venv is widely recognised by editors and tools, and the leading dot hides it on macOS and Linux.
Choosing a specific Python version
A venv uses whichever interpreter created it. To pin a version, call that interpreter explicitly:
# macOS / Linux
python3.12 -m venv .venv
# Windows (Python launcher)
py -3.12 -m venv .venv
You can't change an environment's Python version later; delete the folder and create a new one instead.
Step 2: Activate it
Activation adjusts your shell so python and pip point into the environment.
| Shell | Command |
|---|---|
| macOS / Linux (bash, zsh) | source .venv/bin/activate |
| fish | source .venv/bin/activate.fish |
| Windows PowerShell | .venv\Scripts\Activate.ps1 |
| Windows Command Prompt | .venv\Scripts\activate.bat |
Your prompt usually changes to show (.venv). Confirm it worked:
python -c "import sys; print(sys.prefix)"
The printed path should end in your project's .venv folder.
PowerShell: "running scripts is disabled on this system"
PowerShell's default execution policy can block the activation script. Allow locally created scripts for your user account only:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
You don't strictly have to activate
Activation is a convenience. You can always call the environment's interpreter directly, which is handy in scripts and CI:
.venv/bin/python -m pip install requests # macOS / Linux
.venv\Scripts\python -m pip install requests # Windows
Step 3: Install packages
With the environment active, install packages as usual:
python -m pip install --upgrade pip
python -m pip install requests
Using python -m pip instead of bare pip guarantees you're running the pip that belongs to the active interpreter — a habit that prevents a whole class of "I installed it but Python can't find it" problems.
To leave the environment, run:
deactivate
Step 4: Record and reproduce dependencies
A virtual environment is disposable; your dependency list is what matters.
Saving dependencies
python -m pip freeze > requirements.txt
This writes every installed package with its exact version, for example:
certifi==2026.10.5
charset-normalizer==3.4.2
idna==3.10
requests==2.32.5
urllib3==2.5.0
(The versions above are illustrative; yours will reflect what you installed.)
Recreating the environment elsewhere
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
pip freeze captures everything, including indirect dependencies. Some teams prefer to keep a short list of direct dependencies in pyproject.toml and generate a fully pinned lock file with a tool; either way, the principle is the same — commit the list, not the environment.
Step 5: Keep the environment out of Git
Add the folder to .gitignore:
.venv/
Never commit a virtual environment. It contains absolute paths and platform-specific binaries, so it won't work on another machine anyway.
Fixing "error: externally-managed-environment"
On recent versions of Debian, Ubuntu, Fedora, Homebrew Python and other distributions, running pip install outside a virtual environment produces:
error: externally-managed-environment
× This environment is externally managed
This is deliberate. PEP 668 lets operating systems mark their Python as managed by the system package manager, so pip refuses to modify it and risk breaking OS tools.
The right fix is a virtual environment:
python3 -m venv .venv
source .venv/bin/activate
python -m pip install <package>
On Debian and Ubuntu, if python3 -m venv itself fails with a message about ensurepip, install the venv package first:
sudo apt install python3-venv
For command-line tools you want available everywhere (linters, formatters, CLIs), use pipx, which installs each tool into its own isolated environment automatically.
Avoid --break-system-packages on your own machine unless you fully understand the consequences; as the name says, it can break system packages.
Using virtual environments with your editor
- VS Code: open the Command Palette and choose Python: Select Interpreter, then pick the interpreter inside
.venv. VS Code typically detects.venvin the workspace automatically and activates it in new terminals. - PyCharm: go to Settings → Project → Python Interpreter and add or select the existing
.venvenvironment. - Jupyter: install
ipykernelinside the environment and register it withpython -m ipykernel install --user --name myprojectso it appears as a kernel.
Common mistakes and quick fixes
"ModuleNotFoundError" even though I installed the package.
You installed into a different interpreter. Activate the environment and reinstall with python -m pip install ..., then check python -m pip show <package>.
I moved or renamed the project folder and the environment broke.
Virtual environments contain absolute paths. Delete .venv and recreate it from requirements.txt.
python opens the Microsoft Store on Windows.
That's an "App execution alias". Use the py launcher, or disable the alias under Settings → Apps → Advanced app settings → App execution aliases.
My environment is a mess. That's the beauty of venvs: delete the folder and rebuild it in seconds.
rm -rf .venv # macOS / Linux
# Remove-Item -Recurse -Force .venv # Windows PowerShell
python3 -m venv .venv && source .venv/bin/activate && python -m pip install -r requirements.txt
Beyond venv
The built-in venv module is all most projects need. As projects grow, you may want tools that combine environment management with dependency locking — popular options in the Python ecosystem include Poetry, PDM, Hatch and uv, while Conda is common in data science for managing non-Python dependencies. They all build on the same idea: one isolated environment per project, defined by a file you commit.
Whatever you choose, the habits in this guide carry over: never install project packages into the system Python, always use python -m pip, and commit your dependency list rather than the environment. If you're setting up a new development machine, pair this with our guide to creating SSH keys for GitHub.
Frequently asked questions
+What is a Python virtual environment?
It is an isolated directory containing its own Python interpreter link and its own installed packages, so each project can have its own dependencies without affecting other projects or the system Python.
+Should I commit my venv folder to Git?
No. Virtual environments are tied to the machine and path where they were created. Commit a requirements.txt (or pyproject.toml) instead and add the environment folder to .gitignore.
+Why does pip say 'externally-managed-environment'?
Your operating system marks its Python installation as managed by the system package manager (PEP 668) to stop pip from breaking OS tools. Create a virtual environment and install packages there instead.
+What's the difference between venv and virtualenv?
venv is built into Python 3.3 and later. virtualenv is an older third-party tool with some extra features and speed optimisations. For most projects, the built-in venv is enough.
Sources & references
- Python documentation — venv: Creation of virtual environments
- Python Packaging User Guide — Install packages in a virtual environment using pip and venv
- PEP 405 — Python Virtual Environments
- PEP 668 — Marking Python base environments as 'externally managed'
- pip documentation — Requirements file format
Spotted an error? See our Corrections Policy.
- #python
- #venv
- #pip
- #virtual-environment
- #developer-tools
The KernelBrief editorial desk researches, writes and fact-checks every article published on this site. Every article is checked against primary sources (official documentation, vendor announcements, standards bodies and original research) before publication. Every factual claim is linked to its source, and corrections are handled under our published Corrections Policy.
Related articles
Git Merge vs Rebase Explained: How Each Works, When to Use Them, With Examples
Git merge vs rebase: how each combines branches, when to use which, the golden rule of rebasing, and safe commands for pull, conflicts and force-push.
· 8 min read
LiteLLM Flaw CVE-2026-40217 Is Being Exploited in LLMjacking Attacks: Who Is Affected and How to Patch
CISA added LiteLLM flaw CVE-2026-40217 to its exploited list. Affected versions, why it matters for LLMjacking, and how to patch and rotate keys.
· 7 min read
F5 BIG-IP Buffer Overflow Flaws: Six Critical CVEs, Who Is Affected and How to Patch
F5 disclosed six critical BIG-IP stack buffer overflows (CVSS 9.8) that crash TMM without login. Affected versions, risky configs and hotfixes.
· 4 min read