uv

What I do

I handle the full uv dependency-management lifecycle:

• Add or remove packages — update pyproject.toml and uv.lock in one step
• Sync the environment — install exactly what the lock file specifies, nothing more
• Regenerate the lock file — after you edit pyproject.toml, safely re-resolve without unintended upgrades
• Run commands in the project environment — no manual source .venv/bin/activate needed
• Initialise a new project — create pyproject.toml and uv.lock from scratch, or migrate from requirements.txt

When to use me

• Use this skill when the project is uv-managed (for example, uv.lock exists, or the team standard is uv).
• You want to add, update, or remove a dependency
• You pulled a branch and need the environment to match the updated lock file
• You edited pyproject.toml directly and need the lock file regenerated
• You want to run a script, test suite, or tool inside the project's virtual environment
• You are starting a new Python project with uv, or migrating from pip/requirements.txt

Use Instead [if available]

• Use poetry when the project is Poetry-managed (for example, poetry.lock is the lockfile of record).
• Use ci-fix when your primary goal is diagnosing/remediating a failing CI run instead of general dependency work.

Example usage

/uv add requests
/uv add --dev pytest
/uv remove httpx
/uv sync
/uv lock
/uv run pytest
/uv init

Workflow

Adding and removing dependencies

Add a runtime dependency (goes into [project] dependencies in pyproject.toml):

uv add <package>           # e.g. uv add requests
uv add "<package>>=2.0"    # with version constraint

Add a dev dependency (goes into [dependency-groups] dev — PEP 735, uv's preferred format):

uv add --dev <package>     # e.g. uv add --dev pytest ruff

Dev dependencies are installed in the development environment only and are excluded from production installs. Use --dev for test runners, linters, formatters, and other tooling.

Remove a dependency:

uv remove <package>        # removes from pyproject.toml and updates uv.lock

After every add or remove, uv automatically:

1. Updates pyproject.toml
2. Resolves all constraints and regenerates uv.lock
3. Installs or uninstalls the package in the active environment

Version resolution summary: uv prints the resolved version for each new package, e.g. + requests==2.32.3. If a conflict is detected (a new package's constraints clash with existing ones), uv reports the conflict with the involved packages and constraints — fix the version bounds in pyproject.toml and retry.

Syncing the environment

uv sync installs exactly what uv.lock specifies — no more, no less. It is the canonical way to bring an environment into alignment with the lock file.

uv sync

When to use it:

• After git pull when teammates updated uv.lock
• After checking out a branch with different lock file state
• After manually editing pyproject.toml followed by uv lock (run sync to apply)
• After cloning a repository for the first time

Already in sync: If the environment already matches the lock file, uv sync exits cleanly with no output. It is safe to run on every git pull as a habit.

Dev vs production sync: By default, uv sync includes dev dependencies. Pass --no-dev to sync only runtime dependencies (mirrors production).

uv sync --no-dev    # production-only install

Regenerating the lock file

Use uv lock after editing pyproject.toml directly — for example, changing a version constraint, adding a new dependency entry by hand, or removing one.

Safe default — no unintended upgrades:

uv lock

By default, uv lock resolves only what has changed. Packages already in the lock file are preserved at their current versions if they still satisfy the updated constraints. This is safe to run after any pyproject.toml edit.

Upgrade all dependencies to latest compatible versions:

uv lock --upgrade

This re-resolves all packages to the latest versions permitted by the constraints in pyproject.toml. Review the lock diff carefully before committing.

Upgrade a single package:

uv lock --upgrade-package <package>    # e.g. uv lock --upgrade-package requests

Upgrades only the named package (and its transitive dependencies if required). All other resolved versions remain unchanged.

When to use each variant:

After regenerating the lock file, run uv sync to apply the changes to your environment.

Running commands in the project environment

uv run executes any command inside the project's virtual environment — without requiring manual activation.

uv run <command>

Examples:

uv run pytest                        # run tests
uv run pytest tests/unit/ -v        # with arguments
uv run python src/main.py           # run a script
uv run ruff check .                 # run a tool
uv run python -m mypackage          # module invocation

Auto-sync behaviour: Before running the command, uv automatically syncs the environment if uv.lock has changed since the last sync. This means you never need to remember to run uv sync before executing a command — uv run handles it.

uv run pytest is equivalent to:

source .venv/bin/activate
uv sync
pytest

...but in a single command, with no shell state side-effects.

Replaces manual venv activation: Use uv run <cmd> instead of source .venv/bin/activate && <cmd>. This works consistently across platforms and CI environments.

Initialising a new project

Start a new uv-managed project in the current directory:

uv init

This creates:

• pyproject.toml with a minimal [project] section
• uv.lock (empty lock, ready for uv add)
• .python-version (if Python is pinned)

Pin a specific Python version:

uv python pin 3.12    # writes .python-version with "3.12"

uv reads .python-version automatically on every operation. Pin the version early to ensure consistency across machines and CI.

Migrate from requirements.txt:

1. Create pyproject.toml if it doesn't exist: uv init
2. Copy your dependencies into [project] dependencies:

   [project]
   dependencies = [
     "requests>=2.28",
     "click>=8.0",
   ]
   

3. Generate the lock file: uv lock
4. Sync the environment: uv sync
5. Delete requirements.txt once the migration is verified

For dev requirements (from requirements-dev.txt), add them with uv add --dev <package> instead of copying manually, so they land in [dependency-groups] dev.

Tips for Success

1. uv run replaces venv activation — always use uv run <cmd> instead of activating .venv manually. It works in CI without any setup steps.

2. uv lock is safe by default — it will not upgrade packages that already satisfy your constraints. Run it freely after any pyproject.toml edit.

3. Always review the lock diff after --upgrade — uv lock --upgrade can pull in breaking changes. Check git diff uv.lock before committing and run your test suite.

4. Use uv add --dev for test and lint tools — keeping pytest, ruff, mypy, and similar tools in [dependency-groups] dev ensures they are never installed in production.

5. Run uv sync after every git pull — or just use uv run <cmd> and let auto-sync handle it. Either way, your environment will always match the lock file.

6. Check uv is installed before starting: uv --version. Install with curl -LsSf https://astral.sh/uv/install.sh | sh or brew install uv if missing.

7. Commit uv.lock to version control — the lock file is the source of truth for reproducible environments. Never add it to .gitignore.