Python/uv Development Skill

You are a Python development specialist using uv , an extremely fast Python package manager and project management tool. This skill provides comprehensive workflows, best practices, and common patterns for Python development with uv.

Why uv?

uv is the modern replacement for pip, virtualenv, poetry, and pyenv combined:

• Extremely fast: 10-100x faster than pip

• All-in-one: Package management, virtual environments, Python version management

• Rust-powered: Built for speed and reliability

• Compatible: Works with existing Python projects and tools

IMPORTANT: Avoid pip

DO NOT use pip commands. Always use uv equivalents:

• WRONG: pip install requests → RIGHT: uv add requests

• WRONG: pip install -r requirements.txt → RIGHT: uv sync

• WRONG: pip freeze > requirements.txt → RIGHT: uv lock (creates uv.lock)

• WRONG: python -m pip install → RIGHT: uv run or uv add

The only exception is legacy projects that explicitly require pip compatibility, and even then prefer migrating to uv.

Core Capabilities

• Project Management: init, add, remove, sync, lock

• Running Code: run (scripts and commands)

• Python Management: python (install, list, pin versions)

• Tools: tool (install and run CLI tools)

• Environments: venv (virtual environment creation)

• pip-compatible: pip interface for legacy workflows

• Building: build, publish packages

Quick Start

Running a Python Script

The most common use case - just run your script:

uv run script.py uv run script.py arg1 arg2

What this does:

• Automatically creates/uses virtual environment

• Installs dependencies from pyproject.toml if present

• Runs the script with the correct Python version

Running a Script with Dependencies

Run with additional packages

uv run --with requests script.py uv run --with requests --with pandas analyze.py

Run with packages from requirements file

uv run --with-requirements requirements.txt script.py

Running a Python Module

uv run -m module_name uv run -m pytest tests/ uv run -m black .

One-off Script Execution (No Project)

Run a script in isolation

uv run --isolated script.py

Run with specific Python version

uv run --python 3.11 script.py

Run with dependencies without a project

uv run --with httpx --with rich my_script.py

Project Management

Creating a New Project

Create application project

uv init my-app uv init my-app --app

Create library project

uv init my-lib --lib

Create script (single file)

uv init my-script --script

Create in current directory

uv init

Create without package structure

uv init --bare # Only creates pyproject.toml

Project types:

• --app : Application (not meant to be imported)

• --lib : Library (meant to be published and imported)

• --script : Single-file script with inline dependencies

Managing Dependencies

Add dependency

uv add requests uv add "requests>=2.31.0" uv add requests pandas numpy

Add dev dependency

uv add --dev pytest uv add --dev black ruff mypy

Add optional dependency (extra)

uv add --extra docs sphinx

Remove dependency

uv remove requests uv remove --dev pytest

Update dependencies

uv lock --upgrade uv lock --upgrade-package requests

Syncing Environment

Sync environment with lockfile

uv sync

Sync without dev dependencies

uv sync --no-dev

Sync with all extras

uv sync --all-extras

Sync specific extra

uv sync --extra docs

Exact sync (remove extraneous packages)

uv sync --exact

Lockfile Management

Update lockfile

uv lock

Update all packages

uv lock --upgrade

Update specific package

uv lock --upgrade-package requests

Lock without touching network (use cache only)

uv lock --offline

Python Version Management

Installing Python Versions

Install specific Python version

uv python install 3.11 uv python install 3.12.1

Install multiple versions

uv python install 3.11 3.12

List available Python versions

uv python list

List installed versions

uv python list --only-installed

Finding and Pinning Python

Find Python installation

uv python find uv python find 3.11

Pin project to specific Python version

uv python pin 3.11 uv python pin 3.12.1

This creates/updates .python-version file

Python Version in Projects

When you create a project, uv automatically:

• Creates .python-version file

• Detects or installs the appropriate Python version

• Uses it for all uv run commands in that project

Tool Management

Installing CLI Tools

Install a tool globally

uv tool install ruff uv tool install black uv tool install httpie

Install specific version

uv tool install "black==24.1.0"

Run tool without installing

uv tool run ruff check . uv tool run black --check .

Managing Installed Tools

List installed tools

uv tool list

Upgrade tools

uv tool upgrade ruff uv tool upgrade --all

Uninstall tool

uv tool uninstall ruff

Show tool directory

uv tool dir

Common Tools to Install

Linters and formatters

uv tool install ruff # Fast linter and formatter uv tool install black # Code formatter uv tool install mypy # Type checker

Testing

uv tool install pytest # Test framework uv tool install tox # Test automation

Utilities

uv tool install httpie # HTTP client uv tool install rich-cli # Pretty terminal output uv tool install pipx # Legacy tool installer

Virtual Environments

Creating Virtual Environments

Create venv in current directory

uv venv

Create with specific Python version

uv venv --python 3.11

Create in specific location

uv venv path/to/venv

Create with specific name

uv venv .venv-dev

Using Virtual Environments

Activate (traditional way)

source .venv/bin/activate

Or just use uv run (recommended)

uv run python script.py uv run pytest

Best Practice: With uv, you rarely need to manually activate environments. Just use uv run .

Legacy pip Interface (AVOID - Use Native uv Commands Instead)

WARNING: This interface exists only for legacy compatibility. Prefer native uv commands (uv add , uv sync , uv lock ) over uv pip commands.

Only use uv pip when:

• Working with a legacy project that cannot be migrated yet

• Maintaining compatibility with existing CI/CD that expects pip commands

• As a temporary bridge during migration

Better alternatives:

• uv pip install requests → Use uv add requests instead

• uv pip install -r requirements.txt → Use uv sync instead

• uv pip freeze → Use uv lock instead

Legacy pip-compatible commands (avoid if possible)

uv pip install requests # Better: uv add requests uv pip install -r requirements.txt # Better: uv sync uv pip list # Better: uv tree uv pip show requests # Better: uv tree --package requests uv pip freeze > requirements.txt # Better: uv lock uv pip uninstall requests # Better: uv remove requests

Common Workflows

Workflow 1: New Python Project

1. Create project

uv init my-project --app cd my-project

2. Add dependencies

uv add requests httpx rich

3. Add dev dependencies

uv add --dev pytest black ruff

4. Run your code

uv run python main.py

5. Run tests

uv run pytest

Workflow 2: Working with Existing Project

1. Clone repository

git clone <repo> cd <repo>

2. Sync dependencies (reads pyproject.toml)

uv sync

3. Run the application

uv run python main.py

4. Run tests

uv run pytest

Workflow 3: Quick Script with Dependencies

Option 1: Inline dependencies in script

cat > script.py << 'EOF'

/// script

dependencies = ["requests", "rich"]

///

import requests from rich import print

response = requests.get("https://api.github.com") print(response.json()) EOF

uv run --script script.py

Option 2: Command-line dependencies

uv run --with requests --with rich script.py

Workflow 4: Testing and Linting

Run tests

uv run pytest uv run pytest tests/ uv run pytest -v --cov

Format code

uv run black . uv run ruff format .

Lint code

uv run ruff check . uv run ruff check --fix .

Type check

uv run mypy .

Workflow 5: Dependency Updates

1. Check current dependencies

uv tree

2. Update all dependencies

uv lock --upgrade

3. Update specific package

uv lock --upgrade-package requests

4. Sync environment

uv sync

5. Run tests to verify

uv run pytest

Workflow 6: Building and Publishing

Build package

uv build

Publish to PyPI

uv publish

Publish to test PyPI

uv publish --index https://test.pypi.org/simple/

Best Practices

1. Always Use uv run

Instead of:

Don't do this

source .venv/bin/activate python script.py

Do this:

Do this

uv run script.py

Benefits:

• Automatic environment management

• Ensures dependencies are synced

• Works consistently across systems

2. Pin Python Versions

Always create .python-version file:

uv python pin 3.11

This ensures everyone on the team uses the same Python version.

3. Use Lockfiles

Commit uv.lock to version control:

• Ensures reproducible builds

• Locks transitive dependencies

• Faster installs for teammates

4. Separate Dev Dependencies

uv add --dev pytest black ruff mypy

This keeps production dependencies clean.

5. Use Scripts Section

In pyproject.toml :

[project.scripts] my-cli = "my_package.cli:main"

[tool.uv] dev-dependencies = [ "pytest>=7.0.0", "black>=24.0.0", ]

Then run:

uv run my-cli

Project Structure

Typical uv Project Layout

my-project/ ├── .python-version # Python version (e.g., "3.11") ├── pyproject.toml # Project config and dependencies ├── uv.lock # Lockfile (commit this!) ├── .venv/ # Virtual environment (don't commit) ├── src/ │ └── my_package/ │ ├── init.py │ └── main.py └── tests/ └── test_main.py

pyproject.toml Example

[project] name = "my-project" version = "0.1.0" description = "My awesome project" requires-python = ">=3.11" dependencies = [ "requests>=2.31.0", "rich>=13.0.0", ]

[project.optional-dependencies] dev = [ "pytest>=7.0.0", "black>=24.0.0", "ruff>=0.1.0", ]

[build-system] requires = ["hatchling"] build-backend = "hatchling.build"

[tool.uv] dev-dependencies = [ "pytest>=7.0.0", "black>=24.0.0", ]

Advanced Features

Running with Extras

Run with optional dependencies

uv run --extra docs sphinx-build uv run --all-extras pytest

Dependency Groups

Add to specific group

uv add --group test pytest

Run with specific group

uv run --group test pytest

Sync specific group

uv sync --group test

Environment Variables

Use .env file

uv run --env-file .env script.py

Override env file

uv run --no-env-file script.py

Offline Mode

Work without network

uv run --offline script.py uv sync --offline uv lock --offline

Custom Indexes

Use custom PyPI index

uv add requests --index https://my-pypi.org/simple/

Use multiple indexes

uv add package --index https://index1.org/simple/ --index https://index2.org/simple/

Troubleshooting

Issue: Command not found after uv tool install

Solution: Update shell PATH

uv tool update-shell

Then restart shell or source config

Issue: Python version not found

Solution: Install Python with uv

uv python install 3.11 uv python pin 3.11

Issue: Dependencies not syncing

Solution: Force sync

uv sync --reinstall uv sync --exact

Issue: Cache issues

Solution: Clear cache

uv cache clean uv run --no-cache script.py

Issue: Lock file out of sync

Solution: Regenerate lock

uv lock --upgrade uv sync

Performance Tips

1. Use --frozen for CI/CD

Skip lockfile updates in CI

uv sync --frozen uv run --frozen pytest

2. Leverage Cache

uv automatically caches packages. To see cache:

uv cache dir

3. Parallel Operations

uv automatically parallelizes operations. No configuration needed.

Migration from Other Tools

From pip + virtualenv

Old way

python -m venv .venv source .venv/bin/activate pip install -r requirements.txt python script.py

New way

uv run script.py # That's it!

From Poetry

Old: poetry install && poetry run python script.py

New:

uv sync && uv run python script.py

From Pipenv

Old: pipenv install && pipenv run python script.py

New:

uv sync && uv run python script.py

Integration with Other Tools

pytest

uv run pytest uv run pytest --cov --cov-report=html

black/ruff

uv run black . uv run ruff check --fix .

mypy

uv run mypy src/

jupyter

uv add --dev jupyter uv run jupyter notebook

Quick Reference

Run script

uv run script.py

Run with dependencies

uv run --with requests script.py

Project setup

uv init my-project uv add package-name uv add --dev pytest

Environment management

uv sync uv lock --upgrade

Python management

uv python install 3.11 uv python pin 3.11

Tools

uv tool install ruff uv tool run black .

Legacy compatibility (AVOID - use uv add/sync instead)

uv pip install package # DON'T USE - use: uv add package uv pip install -r requirements.txt # DON'T USE - use: uv sync

Testing and quality

uv run pytest uv run black . uv run ruff check .

Key Differences from pip/virtualenv

Task Old Way uv Way

Create venv python -m venv .venv

uv venv (or automatic)

Activate source .venv/bin/activate

Not needed with uv run

Install deps pip install -r requirements.txt

uv sync

Run script python script.py

uv run script.py

Add package pip install requests

uv add requests

Global tool pip install black

uv tool install black

Common Patterns

Pattern 1: Quick Data Analysis Script

uv run --with pandas --with matplotlib analyze.py

Pattern 2: Testing Before Commit

uv run pytest && uv run black --check . && uv run ruff check .

Pattern 3: Update All Dependencies

uv lock --upgrade && uv sync && uv run pytest

Pattern 4: Run with Specific Python

uv run --python 3.11 script.py

Pattern 5: Install and Run Tool

uv tool run ruff check . # Installs if needed, then runs

Summary

Primary directive: Use uv run for executing Python scripts and commands.

Key advantages:

• No manual environment activation needed

• Automatic dependency management

• Extremely fast operations

• Single tool for all Python workflows

Most common commands:

• uv run script.py

• Run anything

• uv add package

• Add dependency

• uv sync

• Sync environment

• uv python pin 3.11

• Set Python version