Python Virtual Environments Explained (venv and uv)

You install a Python package, run your script, and get ModuleNotFoundError: No module named 'requests' — even though you just installed it. Or pip install refuses with an "externally-managed-environment" error. Both problems have the same answer: virtual environments.

The problem they solve

By default, pip install puts packages into one shared place for your whole computer. That causes trouble:

Project A needs django 4, project B needs django 5. Only one can be installed.
You install something for one project and break another.
You can't tell which packages a project actually needs.
On many Linux systems, the operating system's own tools use that Python — and modifying it can break them.

A virtual environment is a private folder of packages for one project. Each project gets its own, isolated from the others.

Creating one with venv

Python includes venv. In your project folder:

python3 -m venv .venv

(On Windows, use python or py instead of python3.) This creates a .venv folder containing a private copy of the Python interpreter setup and an empty package folder.

Activating it

Activation tells your terminal to use that environment's Python and pip:

System	Command
macOS / Linux	`source .venv/bin/activate`
Windows (PowerShell)	`.venv\Scripts\Activate.ps1`
Windows (Command Prompt)	`.venv\Scripts\activate.bat`

Your prompt changes to show (.venv). Now:

pip install requests
python app.py

installs and runs inside the environment. Type deactivate to leave it.

On Windows, if PowerShell refuses to run the activation script, you may need to allow local scripts for your user: Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.

Recording your dependencies

So others (and your server) can recreate the environment:

pip freeze > requirements.txt     # save
pip install -r requirements.txt   # recreate elsewhere

Commit requirements.txt. Don't commit .venv — add it to .gitignore. Virtual environments are rebuilt, not shared.

Common errors and what they mean

ModuleNotFoundError right after installing: you installed into one Python and ran another — usually the environment wasn't activated in this terminal, or your editor is using a different interpreter. In VS Code, choose Python: Select Interpreter and pick the one in .venv.
error: externally-managed-environment: your operating system (common on recent Ubuntu, Debian and Homebrew Python) is protecting its own Python from pip install. Create a virtual environment and install there. Don't override it with --break-system-packages unless you really know why.
pip: command not found: use python3 -m pip instead.
The environment stopped working after moving the folder: virtual environments contain absolute paths. Delete .venv and recreate it.

uv: the faster modern alternative

uv is a newer Python package and project manager that has become very popular. It does what venv + pip do, much faster, plus more:

uv init my-app        # new project with pyproject.toml
cd my-app
uv add requests       # add a dependency (creates .venv automatically)
uv run python app.py  # run inside the environment — no activation needed

uv records dependencies in pyproject.toml and exact versions in a uv.lock file, like a JavaScript lockfile. It can even install Python versions for you. You can also use it as a drop-in replacement for pip: uv venv and uv pip install -r requirements.txt.

Other tools you'll meet: Poetry (also uses pyproject.toml and a lockfile), and conda (popular in data science, manages non-Python dependencies too).

Which should you use?

Following a tutorial or keeping things minimal: venv + pip — built in, works everywhere.
Starting a new project: uv — faster and with proper lockfiles.
Data science with complex native libraries: conda may be easier.

Whatever you choose, one environment per project, and the dependency file committed to git.

Telling AI tools

AI coding tools sometimes run pip install without activating the environment, or mix pip and uv. Add a line to your project instructions: "This project uses uv. Use uv add to install packages and uv run to run commands." (How to write a CLAUDE.md.)

The summary

A virtual environment is a private set of packages for one project.
python3 -m venv .venv, then activate it, then pip install.
Save dependencies to requirements.txt (or pyproject.toml); never commit .venv.
"externally-managed-environment" means: use a virtual environment.
uv does it all faster, with lockfiles and no activation needed.

EasySpawn servers come ready for Python with pip and uv available, and keep your environments and installed packages on persistent storage — so they're still there next session. See how it works or join the waitlist.

Python Virtual Environments Explained: venv, pip, and uv for Beginners