UV Quickstart Guide for Coding Agents

This guide outlines the standard operating procedures for managing Python projects, scripts, and dependencies using uv.

🚨 CRITICAL RULE: Never use the bare python command. Barely ever should you run python file.py or python -c. Always use uv run to ensure you are executing within the correct, managed environment. If you are stuck or forget a command's syntax, always use uv --help or uv <command> --help.

1. Project Management (Permanent)

When managing a standard Python project, prefer uv's built-in project management over traditional pip workflows.

• Create a new project: uv init
• Add a dependency: uv add <package>
• Remove a dependency: uv remove <package>
• Resync dependencies: uv sync (Use this to clean up the environment or after manually modifying pyproject.toml).

2. Temporary Scripts & Debugging

Do not pollute the global environment or the permanent project files with temporary debugging dependencies.