Virtual Environments Quickstart

A virtual environment isolates project dependencies from system Python and other projects. Create one before installing libraries - it is the first step in any real Python codebase.

Recipe

# uv (recommended)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
 
# stdlib venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

When to reach for this:

Starting any new application or library
Reproducing CI locally with pinned dependencies
Avoiding "works on my machine" version drift
Running tools (ruff, mypy) without global installs

Working Example

# Create project with uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
 
# Run using project interpreter (no manual activate required)
uv run python -c "import fastapi; print(fastapi.__version__)"
 
# Sync from lockfile on a fresh clone
uv sync

# verify_env.py - run with: uv run python verify_env.py
import sys
 
def main() -> None:
    prefix = sys.prefix
    in_venv = sys.prefix != sys.base_prefix
    print(f"prefix={prefix}")
    print(f"isolated={in_venv}")
    print(f"version={sys.version.split()[0]}")
 
if __name__ == "__main__":
    main()

What this demonstrates:

uv venv / uv init creates .venv beside the project
uv add records deps in pyproject.toml and lockfile
uv run executes commands inside the project environment
sys.prefix != sys.base_prefix confirms isolation

Deep Dive

How It Works

venv copies or links base Python interpreter into .venv.
PATH shim - Activation prepends .venv/bin so python resolves locally.
site-packages - Installed wheels land in .venv/lib/python3.14/site-packages.
uv - Rust-based toolchain: fast resolver, lockfile, uv sync, uv run.
PEP 668 - System Python on many Linux distros marks itself "externally managed" - venv required.

Tool Comparison

Tool	Strength
`uv`	Speed, lockfile, project workflow
`venv`	Stdlib, no extra install
`pip-tools`	Legacy compile requirements.in
`poetry` / `pdm`	Full packaging + env management

Python Notes

# Windows activation
.venv\Scripts\activate
 
# Deactivate
deactivate
 
# Which python
which python
python -c "import sys; print(sys.executable)"

Gotchas

Installing globally - Breaks OS tools on Linux/macOS. Fix: Always use venv or uv run.
Committing .venv - Huge and platform-specific. Fix: Gitignore .venv; commit pyproject.toml + lock.
Wrong interpreter in IDE - Runs system Python without deps. Fix: Select .venv/bin/python in editor.
Stale activate shell - Old venv path after rename. Fix: deactivate and re-activate.
Mixed pip and uv - Confusing lock state. Fix: Pick one workflow per repo (prefer uv).

Alternatives

Alternative	Use When	Don't Use When
`uv` project	New apps and libraries	Air-gapped without uv binary
`docker`	Deploy parity	Local syntax checking only
`pyenv`	Multiple Python versions	Single version suffices
`conda`	Scientific stack with binaries	Pure web service

FAQs

Do I must activate the venv?

With uv run, no. For plain python/pip commands, activate or use full path .venv/bin/python.

What goes in .gitignore?

.venv/, __pycache__/, .pytest_cache/, local .env files with secrets.

uv or pip?

uv for new projects - faster installs and lockfiles. pip inside venv is fine for tiny scripts.

How do I recreate a venv?

Delete .venv, run uv sync or uv venv && uv pip install -r requirements.txt.

Can I name the venv folder something else?

Yes - .venv is convention. Update IDE interpreter path accordingly.

How do I pin Python 3.14?

Use pyenv, uv python pin 3.14, or CI matrix python-version: "3.14".

What is uv sync?

Installs dependencies exactly from uv.lock - reproducible clones and CI.

Why externally managed environment error?

PEP 668 protects system Python. Create a venv instead of pip install globally.

How do I install dev tools?

uv add --dev ruff mypy pytest - keeps tools out of production dependency sets when configured.

Does venv include pip?

Yes by default with python -m venv. uv manages pip-compatible installs in its environments.

Modules, Imports & Packages - package layout
uv - the fast toolchain - full uv workflow
pyproject.toml explained - dependency metadata
managing Python versions - pyenv and pins

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Virtual Environments Quickstart

A virtual environment isolates project dependencies from system Python and other projects. Create one before installing libraries - it is the first step in any real Python codebase.

Recipe

# uv (recommended)
uv venv
source .venv/bin/activate
uv pip install httpx pydantic
 
# stdlib venv
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

When to reach for this:

Starting any new application or library
Reproducing CI locally with pinned dependencies
Avoiding "works on my machine" version drift
Running tools (ruff, mypy) without global installs

Working Example

# Create project with uv
mkdir demo-app && cd demo-app
uv init --app
uv add fastapi uvicorn pydantic
 
# Run using project interpreter (no manual activate required)
uv run python -c "import fastapi; print(fastapi.__version__)"
 
# Sync from lockfile on a fresh clone
uv sync

# verify_env.py - run with: uv run python verify_env.py
import sys
 
def main() -> None:
    prefix = sys.prefix
    in_venv = sys.prefix != sys.base_prefix
    print(f"prefix={prefix}")
    print(f"isolated={in_venv}")
    print(f"version={sys.version.split()[0]}")
 
if __name__ == "__main__":
    main()

What this demonstrates:

uv venv / uv init creates .venv beside the project
uv add records deps in pyproject.toml and lockfile
uv run executes commands inside the project environment
sys.prefix != sys.base_prefix confirms isolation

Deep Dive

How It Works

venv copies or links base Python interpreter into .venv.
PATH shim - Activation prepends .venv/bin so python resolves locally.
site-packages - Installed wheels land in .venv/lib/python3.14/site-packages.
uv - Rust-based toolchain: fast resolver, lockfile, uv sync, uv run.
PEP 668 - System Python on many Linux distros marks itself "externally managed" - venv required.

Tool Comparison

Tool	Strength
`uv`	Speed, lockfile, project workflow
`venv`	Stdlib, no extra install
`pip-tools`	Legacy compile requirements.in
`poetry` / `pdm`	Full packaging + env management

Python Notes

# Windows activation
.venv\Scripts\activate
 
# Deactivate
deactivate
 
# Which python
which python
python -c "import sys; print(sys.executable)"

Gotchas

Installing globally - Breaks OS tools on Linux/macOS. Fix: Always use venv or uv run.
Committing .venv - Huge and platform-specific. Fix: Gitignore .venv; commit pyproject.toml + lock.
Wrong interpreter in IDE - Runs system Python without deps. Fix: Select .venv/bin/python in editor.
Stale activate shell - Old venv path after rename. Fix: deactivate and re-activate.
Mixed pip and uv - Confusing lock state. Fix: Pick one workflow per repo (prefer uv).

Alternatives

Alternative	Use When	Don't Use When
`uv` project	New apps and libraries	Air-gapped without uv binary
`docker`	Deploy parity	Local syntax checking only
`pyenv`	Multiple Python versions	Single version suffices
`conda`	Scientific stack with binaries	Pure web service

FAQs

Do I must activate the venv?

With uv run, no. For plain python/pip commands, activate or use full path .venv/bin/python.

What goes in .gitignore?

.venv/, __pycache__/, .pytest_cache/, local .env files with secrets.

uv or pip?

uv for new projects - faster installs and lockfiles. pip inside venv is fine for tiny scripts.

How do I recreate a venv?

Delete .venv, run uv sync or uv venv && uv pip install -r requirements.txt.

Can I name the venv folder something else?

Yes - .venv is convention. Update IDE interpreter path accordingly.

How do I pin Python 3.14?

Use pyenv, uv python pin 3.14, or CI matrix python-version: "3.14".

What is uv sync?

Installs dependencies exactly from uv.lock - reproducible clones and CI.

Why externally managed environment error?

PEP 668 protects system Python. Create a venv instead of pip install globally.

How do I install dev tools?

uv add --dev ruff mypy pytest - keeps tools out of production dependency sets when configured.

Does venv include pip?

Yes by default with python -m venv. uv manages pip-compatible installs in its environments.

Modules, Imports & Packages - package layout
uv - the fast toolchain - full uv workflow
pyproject.toml explained - dependency metadata
managing Python versions - pyenv and pins

Stack versions: This page was written for Python 3.14.0 (stable 3.14, maintenance 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, and uv 0.6+.

Virtual Environments Quickstart

Search Documentation

Virtual Environments Quickstart