Python uv Best Practices: Stability & Collaboration Checklist
In practice, environments tend to break not because "uv isn't powerful enough," but because of process and habits. This checklist can be used as daily guidelines — every pitfall avoided is another time you leave work on time.
Recommended Practices
1) Always Commit uv.lock
The lockfile is the foundation of reproducibility. Not committing it means everyone, every machine, every CI run may install different dependencies — reproducing bugs becomes hell mode. A project without a lockfile is like new shoes you've never tried on: you only find out they hurt when you're in battle.
2) Never Commit .venv
The virtual environment is a local artifact — it should be in .gitignore. uv automatically adds .venv to the project's ignore file; just double-check it's there.
3) Constrain Dependencies When Possible
In pyproject.toml, avoid bare requests — prefer requests>=2.31,<3 or more specific. uv add adds reasonable constraints by default; when editing manually, don't leave the range too wide.
4) Use uv sync or uv pip sync in CI
# GitHub Actions example
- run: uv sync
- run: uv run pytestSync first, then run — ensures the environment matches the lockfile. Don't run uv add in CI; that modifies the lockfile and can create unexpected diffs.
5) Put Dev Tools in optional / dev
uv add --dev pytest ruff mypyTests, lint, and type checking don't affect production dependencies and won't be packed into the wheel. Production images only need uv sync --no-dev.
Common Pitfalls
Pitfall 1: Mixing pip and uv add
Don't use both pip install and uv add in the same venv — the lockfile will get out of sync. Pick one path and stick to it.
Pitfall 2: Using uvx for Project Tools
Project tools that need a pinned version (like pytest, mypy) → use uv add --dev + uv run.
Temporary one-off use → use uvx.
Pitfall 3: Editing pyproject.toml Manually Without Reading It First
For dependency changes, prefer uv add / uv remove — avoids format issues and missing lockfile updates.
Pitfall 4: Not Installing uv in CI
Many CI systems now support uv — it installs fast and runs even faster. Use the official installer or pip install uv; don't stick with pip for dependency resolution forever.
Pitfall 5: No requires-python in the Project
In pyproject.toml, specify requires-python = ">=3.12" etc., so tools and collaborators know the minimum version requirement. Prevents the disaster of "it runs on my 3.12, it crashes on your 3.8."
Following this checklist won't guarantee zero failures, but you'll avoid a lot of unnecessary detours. Check the official docs when in doubt — most pitfalls have been stumbled into before. Happy developing — may your dependencies install cleanly, tests stay green, and CI stop making you wait forever! 🦦 (By the way, after using uv, you'll realize: the time you used to spend waiting for pip's spinner is now enough to pet the cat three times.)