사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/laurigates/claude-plugins --skill uv-run시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
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/
