Virtual Environments & Dependency Management¶

Status: 🟢 Active  |  Owner: Python Guild

Approved Tools¶

Poetry is the standard for all new Python services and libraries.

Poetry Project Setup¶

# New project
poetry new my-service
cd my-service

# Add dependencies
poetry add fastapi pydantic sqlalchemy

# Add dev dependencies
poetry add --group dev pytest black ruff mypy

# Install with lockfile
poetry install

# Run in venv
poetry run python -m my_service

pyproject.toml Standard¶

[tool.poetry]
name = "order-service"
version = "1.0.0"
description = "Manages order lifecycle"
authors = ["Order Team <[email protected]>"]
python = "^3.10"

[tool.poetry.dependencies]
python = "^3.10"
fastapi = "0.110.0"
pydantic = "^2.6"
sqlalchemy = "^2.0"

[tool.poetry.group.dev.dependencies]
pytest = "^8.0"
black = "^24.0"
ruff = "^0.3"
mypy = "^1.9"
pytest-cov = "^5.0"

Lockfile Requirements¶

• poetry.lock must be committed to the repository.
• In CI, use poetry install --no-root --sync to reproduce the exact environment.
• Never use pip install -r requirements.txt for services — use Poetry.

Virtual Environment Policy¶

• Never install packages in the global Python environment.
• In Docker builds, use a venv even inside containers to support multi-stage builds.

Last reviewed: 2025-Q4  |  Owner: Python Guild