How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/laurigates/claude-plugins --skill uv-runBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
UV Run
Run Python scripts with uv - no manual venv activation needed.
When to Use This Skill
| Use this skill when... | Use a focused sibling instead when... |
|---|---|
Running a one-off script with uv run script.py and no project context | Adding a long-lived dependency to a project — use uv-project-management |
Embedding PEP 723 inline metadata or --with deps into a self-contained script | Installing a global CLI tool (uv tool install / uvx) — use uv-tool-management |
| Executing project commands inside the project venv without manual activation | Authoring the project's pyproject.toml or lockfile — use uv-project-management |
Core Capabilities
- Direct execution:
uv run script.pyhandles environment automatically - Temporary dependencies:
uv run --with requests script.pyfor one-off needs - Inline dependencies: PEP 723 metadata blocks for self-contained scripts
- Ephemeral tools:
uvx toolruns CLI tools without installation
Essential Commands
Running Scripts
bash
# Run script (uv manages environment automatically)
uv run script.py
# Run with arguments
uv run script.py --input data.csv --output results.json
# Run a specific module
uv run -m http.server 8000
# Run with specific Python version
uv run --python 3.12 script.pyTemporary Dependencies
Add dependencies for a single run without modifying project:
bash
# Single dependency
uv run --with requests fetch_data.py
# Multiple dependencies
uv run --with requests --with rich api_client.py
# Version constraints
uv run --with 'requests>=2.31' --with 'rich>12,<14' script.py
# Combine with project dependencies
uv run --with pytest-benchmark pytest # Add benchmark to existing pytestInline Script Dependencies (PEP 723)
Create self-contained scripts with embedded dependencies:
python
#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.11"
# dependencies = [
# "requests>=2.31",
# "rich>=13.0",
# ]
# ///
import requests
from rich import print
response = requests.get("https://api.github.com")
print(response.json())Run directly:
bash
uv run script.py
# Or make executable:
chmod +x script.py
./script.pyManaging Script Dependencies
bash
# Initialize script with metadata
uv init --script example.py --python 3.12
# Add dependency to script
uv add --script example.py requests rich
# Lock script dependencies for reproducibility
uv lock --script example.pyEphemeral Tool Execution (uvx)
Run CLI tools without installation:
bash
# Run tool once
uvx pycowsay "Hello from uv!"
uvx httpie https://api.github.com
uvx ruff check .
# With specific version
uvx ruff@0.1.0 check .
# uvx is shorthand for:
uv tool run pycowsay "Hello"Shebang Patterns
Self-Contained Executable Script
python
#!/usr/bin/env -S uv run --script
# /// script
# dependencies = ["click", "rich"]
# ///
import click
from rich import print
@click.command()
@click.argument('name')
def hello(name):
print(f"[green]Hello, {name}![/green]")
if __name__ == "__main__":
hello()Script with Python Version Requirement
python
#!/usr/bin/env -S uv run --script --python 3.12
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///
import httpx
# Uses Python 3.12+ featuresWhen to Use Each Pattern
| Scenario | Approach |
|---|---|
| Quick one-off task | uv run --with pkg script.py |
| Reusable script | Inline deps (PEP 723) |
| Shareable utility | PEP 723 + shebang |
| Team collaboration | Inline deps + uv lock --script |
| Run CLI tool once | uvx tool |
| Project scripts | uv run (uses project deps) |
uvx vs uv run --with
- `uvx tool`: Run a CLI tool without installation (e.g.,
uvx ruff check .) - `uv run --with pkg`: Run a script with temporary dependencies (e.g.,
uv run --with requests script.py)
bash
# Run a tool (CLI application)
uvx httpie https://api.github.com
# Run a script with dependencies
uv run --with httpx api_test.pyProfiling and Debugging
bash
# CPU profiling
uv run python -m cProfile -s cumtime script.py | head -20
# Line-by-line profiling (temporary dependency)
uv run --with line-profiler kernprof -l -v script.py
# Memory profiling
uv run --with memory-profiler python -m memory_profiler script.py
# Real-time profiling (ephemeral tool)
uvx py-spy top -- python script.py
# Quick profiling
uv run --with scalene python -m scalene script.pySee Also
- uv-project-management - Project dependencies and lockfiles
- uv-tool-management - Installing CLI tools globally
- python-development - Core Python language patterns
References
- Official docs: https://docs.astral.sh/uv/guides/scripts/
- PEP 723: https://peps.python.org/pep-0723/
- Tools: https://docs.astral.sh/uv/guides/tools/
