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.
//
Search across all documentation pages
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.
# 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 pipWhen to reach for this:
# 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 projectuv add records deps in pyproject.toml and lockfileuv run executes commands inside the project environmentsys.prefix != sys.base_prefix confirms isolation.venv..venv/bin so python resolves locally..venv/lib/python3.14/site-packages.uv sync, uv run.| Tool | Strength |
|---|---|
uv | Speed, lockfile, project workflow |
venv | Stdlib, no extra install |
pip-tools | Legacy compile requirements.in |
poetry / pdm | Full packaging + env management |
# Windows activation
.venv\Scripts\activate
# Deactivate
deactivate
# Which python
which python
python -c "import sys; print(sys.executable)"uv run..venv; commit pyproject.toml + lock..venv/bin/python in editor.deactivate and re-activate.| 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 |
With uv run, no. For plain python/pip commands, activate or use full path .venv/bin/python.
.venv/, __pycache__/, .pytest_cache/, local .env files with secrets.
uv for new projects - faster installs and lockfiles. pip inside venv is fine for tiny scripts.
Delete .venv, run uv sync or uv venv && uv pip install -r requirements.txt.
Yes - .venv is convention. Update IDE interpreter path accordingly.
Use pyenv, uv python pin 3.14, or CI matrix python-version: "3.14".
Installs dependencies exactly from uv.lock - reproducible clones and CI.
PEP 668 protects system Python. Create a venv instead of pip install globally.
uv add --dev ruff mypy pytest - keeps tools out of production dependency sets when configured.
Yes by default with python -m venv. uv manages pip-compatible installs in its environments.
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+.
Reviewed by Chris St. John·Last updated Jul 16, 2026