uv best practices

Use when building or reviewing Python workflows that rely on uv for project management, dependency resolution, virtual environments, Python installation, tool execution, or the uv pip compatibility layer.

Mental model

• Treat uv as the control plane for Python project setup, environments, dependencies, tools, and interpreter management, not as a thin wrapper around pip.
• Prefer one clear workflow per repo: either project mode (uv init, uv add, uv sync, uv run) or the pip-compatible interface (uv pip ...) for ad hoc environments. Do not mix them casually.
• Keep dependency intent in pyproject.toml and let uv own locking and syncing instead of hand-editing multiple derived files without a reason.

Projects and dependencies

• For application or library repos, prefer project mode with pyproject.toml and the uv lockfile.
• Use uv add and uv remove for routine dependency changes so manifests and lock state stay aligned.
• Use dependency groups for local-only tooling such as test, lint, and docs dependencies instead of polluting published runtime dependencies.
• Keep project.dependencies for published requirements and tool.uv.sources for development-only alternate sources such as local paths, Git, indexes, or workspace members.

Sync and execution