How to create and use a Python virtual environment with venv

A README says “create a virtual environment” before it tells you what that means. Use Python’s built-in venv module to create one, activate it, and install packages into the right place. For the concepts, see What is a virtual environment?. For a new project from scratch, uv handles all of this for you.

Create the environment

Run this from your project directory:

python3 -m venv .venv

py -m venv .venv

This creates a .venv/ folder containing its own Python interpreter and site-packages/ directory. The leading dot keeps the folder hidden from most file listings, and most tools recognize .venv as the default environment location. Add it to .gitignore so the environment stays out of source control.

Activate it on your platform

Activation rewrites the shell’s PATH so python and pip resolve to the environment’s copies.

source .venv/bin/activate

source .venv/bin/activate.fish

.venv\Scripts\Activate.ps1

.venv\Scripts\activate.bat

The shell prompt usually prefixes with (.venv) once activation succeeds. Running which python on macOS/Linux or where.exe python on Windows should now point inside .venv/.

Install packages

Install a single package:

pip install requests

Install everything a requirements.txt lists:

pip install -r requirements.txt

Snapshot the current environment back out to a file:

pip freeze > requirements.txt

Run Python and scripts

While the environment is active, python uses the venv’s interpreter and imports the venv’s packages:

python main.py
python -m pytest
python

python -m pytest runs pytest against your project, and a bare python opens an interactive REPL with the installed packages available.

Deactivate when you’re done

deactivate

This restores the original PATH. The environment still exists on disk; activate it again to pick up where you left off.

Start fresh if the environment breaks

A broken environment is disposable. Delete and recreate it:

deactivate  # if active
rm -rf .venv
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

deactivate  # if active
Remove-Item -Recurse -Force .venv
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

If there is no requirements.txt, you have to reinstall whatever packages the project needs by hand. That’s one reason a lockfile matters for reproducible builds.

Skip all this with uv

For a new project, uv replaces this entire lifecycle with one command:

uv run main.py

uv creates the virtual environment, installs dependencies from pyproject.toml, and runs the script in one shot. There’s no activation step and no “did I install this in the right env?” guessing.

Run your first Python script with uv is the fastest starting point, and Create your first Python project with uv scaffolds a full project from scratch. If you already have a requirements.txt, migrate it to pyproject.toml with uv in a few steps.

Learn More

• What is a virtual environment? explains what the .venv directory actually contains and how isolation works.
• Why should I use a virtual environment? covers the problems virtual environments solve.
• venv reference documents every venv flag and edge case.
• How to fix the “externally-managed-environment” error handles the PEP 668 block you may have hit before landing here.