Script Execution

Relevant source files

• crates/uv-requirements/src/sources.rs
• crates/uv-requirements/src/specification.rs
• crates/uv-scripts/src/lib.rs
• crates/uv/src/commands/project/add.rs
• crates/uv/src/commands/project/export.rs
• crates/uv/src/commands/project/lock.rs
• crates/uv/src/commands/project/mod.rs
• crates/uv/src/commands/project/remove.rs
• crates/uv/src/commands/project/run.rs
• crates/uv/src/commands/project/sync.rs
• crates/uv/src/commands/project/tree.rs
• crates/uv/src/commands/tool/mod.rs
• crates/uv/tests/it/tool_install.rs
• crates/uv/tests/it/tool_run.rs

This document describes uv's support for single-file Python scripts with inline dependency metadata, following PEP 723. Script execution enables running Python files with dependencies specified directly within the script, without requiring a full project structure or separate requirements.txt files.

For information about running commands in projects with pyproject.toml files, see Project Commands. For general Python environment management, see Python Environment Management.

Overview

uv's script execution system provides three primary capabilities:

1. Inline Metadata Parsing: Extracts PEP 723 metadata blocks from Python scripts to determine dependencies and Python version requirements
2. Environment Management: Creates and caches isolated environments for each script based on its dependencies
3. Lockfile Support: Optionally generates uv.lock files for scripts to ensure reproducible dependency resolution

Scripts can be executed from local files, stdin, or remote URLs. The system automatically handles environment creation, dependency installation, and command execution.

Sources: crates/uv/src/commands/project/run.rs1-1500

PEP 723 Inline Metadata Format

PEP 723 defines a standard for embedding TOML metadata within Python script comments. The metadata block must:

• Begin with # /// script on a line by itself
• Contain valid TOML in subsequent comment lines (starting with #)
• End with # /// on a line by itself
• Appear within the first 512 bytes of the file (after any shebang)

Metadata Structure

The metadata follows a TOML schema with these key fields:

• dependencies: Array of PEP 508 dependency specifiers
• requires-python: Version specifier for Python compatibility
• tool.uv.*: uv-specific configuration (indexes, sources, constraints, etc.)

Example:

Sources: crates/uv-scripts/src/lib.rs158-266

Metadata Parsing Implementation

Diagram: PEP 723 Metadata Parsing Pipeline

Sources: crates/uv-scripts/src/lib.rs21-266 crates/uv-scripts/src/lib.rs410-500

Key Data Structures

Structure	Purpose	Location
Pep723Item	Enum for script types (Script/Stdin/Remote)	crates/uv-scripts/src/lib.rs23-69
Pep723Script	Script with path and parsed metadata	crates/uv-scripts/src/lib.rs159-169
Pep723Metadata	Parsed TOML metadata structure	crates/uv-scripts/src/lib.rs401-500
Pep723ItemRef<'item>	Borrowed reference to script	crates/uv-scripts/src/lib.rs72-150
ScriptTag	Raw metadata block extraction	crates/uv-scripts/src/lib.rs410-500

Sources: crates/uv-scripts/src/lib.rs1-500

Script Types and Sources

uv supports three sources for Python scripts:

Local File Scripts

Scripts read from the local filesystem. These are the most common case and support all features including lockfile generation.

Key Functions:

• Pep723Script::read(): Reads and parses script from file crates/uv-scripts/src/lib.rs177-200
• ScriptInterpreter::root(): Determines cache location crates/uv/src/commands/project/mod.rs580-658

Stdin Scripts

Scripts provided via standard input. These create ephemeral environments and do not support lockfiles.

The system prevents conflicts when both script and requirements are read from stdin crates/uv/src/commands/project/run.rs152-159

Remote URL Scripts

Scripts fetched from remote URLs (e.g., GitHub Gists). Environments are cached based on URL hash.

GitHub Gist Support: The system includes special handling for GitHub Gists crates/uv/src/commands/project/run.rs49-58:

Sources: crates/uv/src/commands/project/run.rs209-227 crates/uv-scripts/src/lib.rs23-69

Environment Management

Script environments are isolated Python virtual environments created specifically for a script's dependencies. The system uses two strategies: cached environments (for scripts with metadata) and ephemeral environments (for scripts without metadata).

Diagram: Script Environment Resolution Flow

Sources: crates/uv/src/commands/project/mod.rs574-790 crates/uv/src/commands/project/run.rs208-509

Environment Location Strategy

The ScriptInterpreter::root() function determines where environments are stored crates/uv/src/commands/project/mod.rs580-658:

Script Type	Cache Key	Path Pattern
Local Script	cache_digest(&script.path)	<cache>/environments/<name>-<digest>/
Remote URL	cache_digest(url)	<cache>/environments/<digest>/
Stdin	cache_digest(&metadata.raw)	<cache>/environments/<digest>/

The function also respects VIRTUAL_ENV when --active is used, allowing scripts to run in the active environment crates/uv/src/commands/project/mod.rs627-654

Environment Validation

The environment_is_usable() function checks whether an existing environment can be reused crates/uv/src/commands/project/mod.rs825-900:

Validation Checks:

1. Python version matches pyvenv.cfg configuration
2. Python version satisfies python_request if provided
3. Python version satisfies requires-python from metadata
4. Python preference is satisfied (managed vs system)

Sources: crates/uv/src/commands/project/mod.rs825-900

ScriptInterpreter Discovery

The ScriptInterpreter enum represents either a new interpreter or an existing environment:

The ScriptInterpreter::discover() method crates/uv/src/commands/project/mod.rs661-751:

1. Determines the cache location via ScriptInterpreter::root()
2. Attempts to read existing environment via PythonEnvironment::from_root()
3. Validates environment with environment_is_usable()
4. If invalid/missing, finds or downloads a suitable Python interpreter
5. Returns either Environment (reuse) or Interpreter (create new)

Sources: crates/uv/src/commands/project/mod.rs564-790

Lockfile Support

Scripts can optionally have lockfiles (uv.lock) for reproducible dependency resolution. Lockfiles are stored adjacent to the script with the pattern <script>.lock or in a .uv/ directory.

Lockfile Detection

The system checks for existing lockfiles using LockTarget::from() crates/uv/src/commands/project/lock_target.rs:

When a lockfile exists, the script execution flow includes locking and syncing crates/uv/src/commands/project/run.rs229-358

Locking Process

Diagram: Script Lockfile Resolution Flow

Sources: crates/uv/src/commands/project/run.rs229-358 crates/uv/src/commands/project/lock.rs81-253

Lock Modes

Scripts support three lock modes crates/uv/src/commands/project/lock.rs255-265:

Mode	Description	When Used
Frozen	Use existing lock without validation	--frozen flag
Locked(interpreter, source)	Validate lock is current, error if not	--locked or --check-locked
Write(interpreter)	Update lock if needed	Default behavior

The lock mode is determined in run.rs crates/uv/src/commands/project/run.rs264-271:

Lockfile Storage

For local scripts, lockfiles are stored using LockTarget::lock_path():

• Pattern: <script-dir>/<script-name>.lock or <script-dir>/.uv/<script-name>.lock
• Example: script.py → script.py.lock or .uv/script.py.lock

Sources: crates/uv/src/commands/project/run.rs229-358 crates/uv/src/commands/project/lock.rs255-433

Dependency Management

Scripts support adding and removing dependencies through the uv add and uv remove commands, which modify the inline metadata.

Adding Dependencies

The add command handles scripts via AddTarget::Script crates/uv/src/commands/project/add.rs178-245:

Add Flow:

1. Parse or initialize script metadata crates/uv/src/commands/project/add.rs203-222
2. Discover interpreter via ScriptInterpreter::discover() crates/uv/src/commands/project/add.rs228-243
3. Resolve requirements crates/uv/src/commands/project/add.rs372-496
4. Modify TOML via PyProjectTomlMut crates/uv/src/commands/project/add.rs517-900
5. Write updated script crates/uv/src/commands/project/add.rs923-952
6. Update lockfile if present crates/uv/src/commands/project/add.rs1013-1060

Removing Dependencies

The remove command uses RemoveTarget::Script crates/uv/src/commands/project/remove.rs66-283:

Remove Flow:

1. Load script metadata into PyProjectTomlMut crates/uv/src/commands/project/remove.rs116-123
2. Remove dependency from TOML crates/uv/src/commands/project/remove.rs125-178
3. Write updated content crates/uv/src/commands/project/remove.rs183
4. Update lockfile if exists crates/uv/src/commands/project/remove.rs192-201

TOML Manipulation

Both operations use PyProjectTomlMut with DependencyTarget::Script to preserve formatting crates/uv/src/commands/project/add.rs117:

This ensures comments and structure are preserved when modifying dependencies.

Sources: crates/uv/src/commands/project/add.rs178-1100 crates/uv/src/commands/project/remove.rs66-448

Execution Flow

The complete script execution flow integrates all components from parsing to running the command.

Diagram: Complete Script Execution Pipeline

Sources: crates/uv/src/commands/project/run.rs80-1400

Main Entry Point

The run() function is the main entry point crates/uv/src/commands/project/run.rs80-113:

Key Parameters:

• script: The PEP 723 item if detected
• command: The command to execute (or Python stdin/gui)
• requirements: Additional --with requirements
• frozen, lock_check: Lockfile behavior controls

Script Detection and Parsing

The script is detected and parsed before the run() call. Within run(), the system handles three paths crates/uv/src/commands/project/run.rs210-509:

1. Script with lockfile: Full lock + sync flow crates/uv/src/commands/project/run.rs229-358
2. Script with metadata (no lockfile): Direct environment update crates/uv/src/commands/project/run.rs374-469
3. Script without metadata: Isolated temp environment crates/uv/src/commands/project/run.rs471-505

Environment Loading

For scripts with metadata, ScriptEnvironment::get_or_init() handles environment creation crates/uv/src/commands/project/environment.rs:

This function:

1. Determines environment location via ScriptInterpreter::root()
2. Attempts to load existing environment
3. Validates Python version and preferences
4. Creates new environment if needed

Additional Requirements (--with)

Scripts support --with for additional dependencies crates/uv/src/commands/project/run.rs955-1100:

These create an overlay environment via .pth files crates/uv/src/commands/project/run.rs1100-1250:

1. Install --with deps to cached environment
2. Create .pth file pointing to cached site-packages
3. Execute command with modified sys.path

Command Execution

Finally, the command is executed via run_to_completion() crates/uv/src/commands/project/run.rs1350-1400:

This spawns the process with:

• Modified PATH to include script environment's bin directory
• Correct VIRTUAL_ENV environment variable
• Original working directory preserved

Sources: crates/uv/src/commands/project/run.rs80-1400 crates/uv/src/child.rs

Command Integration

Script execution integrates with several other uv commands beyond uv run.

Supported Commands

Command	Script Support	Behavior
uv run	Full	Execute script with dependencies
uv add	Full	Add dependencies to inline metadata
uv remove	Full	Remove dependencies from inline metadata
uv sync	Full	Sync script environment with lockfile
uv lock	Full	Generate/update lockfile for script
uv tree	Full	Show dependency tree for script
uv export	Full	Export requirements from script

Script Initialization

The uv add and uv lock commands can initialize PEP 723 metadata if it doesn't exist crates/uv/src/commands/project/add.rs206-220:

This uses Pep723Script::init_metadata() to generate default metadata crates/uv-scripts/src/lib.rs222-266:

• Preserves shebang line if present
• Adds default dependencies = []
• Includes requires-python if specified
• Maintains proper formatting

Export Formats

Scripts can be exported to various formats via uv export crates/uv/src/commands/project/export.rs58-461:

Supported formats:

• requirements.txt format with --format requirements-txt
• PEP 751 pylock.toml format with --format pylock
• CycloneDX JSON for SBOM generation

Sources: crates/uv/src/commands/project/add.rs178-245 crates/uv/src/commands/project/lock.rs82-253 crates/uv/src/commands/project/export.rs37-461

Recursion Protection

Script execution includes protection against infinite recursion when scripts use shebangs like #!/usr/bin/env -S uv run.

Recursion Detection

The system tracks recursion depth via environment variable crates/uv/src/commands/project/run.rs114-127:

Implementation Details:

• Environment variable: UV_INTERNAL__RECURSION_DEPTH
• Default limit: Configurable via CLI (max_recursion_depth parameter)
• Incremented on each uv run invocation
• Provides helpful error message suggesting --script flag

This prevents infinite loops when:

1. Script has shebang: #!/usr/bin/env -S uv run
2. Script is executed directly: ./script.py
3. OS executes shebang, which calls uv run script.py
4. uv run executes script, which triggers shebang again

The --script flag bypasses this by explicitly marking script execution mode.

Sources: crates/uv/src/commands/project/run.rs114-127