playbooks

home / skills / benchflow-ai / skillsbench / astral-uv

astral-uv skill

/registry/terminal_bench_2.0/full_batch_reviewed/terminal_bench_2_0_modernize-scientific-stack/environment/skills/astral-uv

This skill optimizes Python project setup and dependency management using Astral UV, speeding installs, venv creation, and script execution for developers.

npx playbooks add skill benchflow-ai/skillsbench --skill astral-uv

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.0 KB
---
name: astral-uv
description: >
  Fast Python package and project management using Astral's uv. Use when
  installing packages, managing virtual environments, running Python scripts,
  or initializing Python projects. Triggers on: pyproject.toml, requirements.txt,
  Python dependency discussions, virtual environment setup.
license: MIT
metadata:
  author: Ian
  version: "1.0"
---

# Astral UV

UV is an extremely fast Python package installer and resolver written in Rust.

## Quick Reference

| Task | Command |
|------|---------|
| Create venv | `uv venv` |
| Install package | `uv pip install <pkg>` |
| Add dependency | `uv add <pkg>` |
| Run script | `uv run <script.py>` |
| Sync dependencies | `uv sync` |
| Init project | `uv init` |

## Project Management

Initialize a new project:
```bash
uv init my-project
cd my-project
```

Add dependencies (updates pyproject.toml automatically):
```bash
uv add requests httpx
uv add --dev pytest ruff
```

Sync environment with lockfile:
```bash
uv sync
```

## Running Code

Run scripts without manual venv activation:
```bash
uv run python script.py
uv run pytest
uv run ruff check .
```

Run with inline dependencies:
```bash
uv run --with requests script.py
```

## Virtual Environments

```bash
uv venv                    # Create .venv
uv venv --python 3.12      # Specific Python version
```

## pip Interface

Drop-in pip replacement (10-100x faster):
```bash
uv pip install requests
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
```

## Python Version Management

```bash
uv python install 3.12     # Install Python version
uv python list             # Show available versions
uv python pin 3.12         # Pin version for project
```

## Best Practices

1. Prefer `uv add` over `uv pip install` for project dependencies
2. Use `uv run` instead of activating venvs manually
3. Commit `uv.lock` to version control
4. Use `uv sync --frozen` in CI for reproducible builds
5. Add dev dependencies with `uv add --dev`

Overview

This skill provides fast Python package and project management using Astral's uv tool. It streamlines creating virtual environments, installing and syncing dependencies, running scripts, and initializing projects with a minimal command surface. The skill is optimized for workflows triggered by pyproject.toml, requirements.txt, dependency discussions, or virtual environment setup.

How this skill works

The skill maps common Python project tasks to uv commands: create .venv with uv venv, add dependencies with uv add, install packages via uv pip, and run scripts with uv run without manual venv activation. It also supports locking and syncing environments (uv sync), managing Python versions (uv python ...), and CI-friendly reproducible installs with uv sync --frozen. The skill updates pyproject.toml and uv.lock where appropriate to keep project metadata and dependency locks consistent.

When to use it

  • Starting a new Python project and initializing tooling with uv init
  • Adding or upgrading dependencies and updating pyproject.toml (uv add)
  • Setting up or recreating a virtual environment (uv venv) for development
  • Running scripts or test suites without activating virtualenvs (uv run)
  • Pinning and installing specific Python versions for a project (uv python)
  • Ensuring CI reproducible installs using uv sync --frozen

Best practices

  • Use uv add to declare project dependencies so pyproject.toml is updated automatically
  • Commit uv.lock to version control for reproducible environments
  • Prefer uv run to avoid manual venv activation during development and automation
  • Use uv sync --frozen in CI to ensure deterministic installs
  • Add development tools with uv add --dev to keep runtime and dev deps separate

Example use cases

  • Initialize a new repo: uv init my-project then cd my-project and uv venv
  • Add runtime and dev dependencies: uv add requests httpx; uv add --dev pytest ruff
  • Install from requirements.txt quickly: uv pip install -r requirements.txt
  • Run tests without activating venv: uv run pytest
  • Pin Python version for the project and install it: uv python pin 3.12; uv python install 3.12

FAQ

Do I need to activate the virtual environment created by uv?

No. Use uv run to execute commands inside the project environment without manual activation, though uv venv still creates a local .venv you can activate if desired.

Should I commit uv.lock to my repository?

Yes. Committing uv.lock ensures consistent, reproducible installs across machines and CI.