uv-run

Run a Python script

$ uv run [script.py]

$ uv run [[-m|--module]] [module_name]

$ uv run --with [package] [command]

$ uv run --with-requirements [requirements.txt] [script.py]

$ uv run --isolated [script.py]

$ uv run --no-sync [command]

uv-run [OPTIONS] [-- COMMAND [ARGUMENTS...]]

Note: This command is typically invoked as uv run, where uv is the main executable.

--env
    Sets an environment variable for the executed command. Can be specified multiple times.

--python
    Specifies the Python version to use for the command. E.g., '3.10', '3.11'.

--isolated
    Runs the command in a temporary, isolated environment, useful for testing or one-off tasks.

--with
    Installs additional packages specifically for the duration of this command's execution. Can be repeated.

--strict
    Aborts the command execution if any required dependencies are missing or unresolved.

--from-stdin
    Reads the script or commands to execute directly from standard input.

--help
    Displays the help message for the uv run subcommand and exits.

--verbose
    Enables verbose output, showing more details about the execution process.

--quiet
    Suppresses informational output, showing only errors or critical messages.

The uv-run command, more commonly invoked as uv run, is a powerful subcommand of the uv package installer and dependency resolver. Its primary purpose is to execute Python scripts or arbitrary shell commands within the context of a uv-managed virtual environment.

Unlike directly invoking python script.py, uv run ensures that the command is executed with the exact Python interpreter and dependencies configured for the current uv project. This eliminates potential conflicts arising from system-wide Python installations or mismatched library versions. It's particularly useful for development workflows where consistency and reproducibility are paramount, allowing developers to quickly test scripts or run project-specific tools in an isolated, controlled environment.

The uv tool itself is known for its exceptional speed, being written in Rust, making uv run a very fast option for running Python-based tasks within its ecosystem.

It is crucial to understand that uv-run is not a standalone executable but a subcommand of the uv tool. Users must have uv installed and typically invoke it as uv run. The command relies on an existing or implicitly managed uv environment to resolve dependencies and select the Python interpreter. Misconfiguration of the uv environment or project may lead to unexpected behavior or errors.

uv-run (as uv run) is tightly integrated with uv's broader capabilities, including dependency resolution (uv install, uv sync), virtual environment management (uv venv), and lockfile generation (uv lock). It leverages the performance and reliability of uv to ensure that scripts always run with the correct and consistent set of packages and Python interpreter.

Many general uv options can also be applied to the run subcommand. These include options related to network proxy settings (--proxy), connection timeouts (--connect-timeout), and output coloring (--color), providing consistent behavior across the uv CLI.

uv is a relatively recent entrant into the Python packaging ecosystem, developed by Astral (now known as ruff-dev). Launched with significant fanfare, it aims to provide an extremely fast and reliable alternative to traditional tools like pip, pip-tools, and venv. Its core is written in Rust, which contributes to its remarkable performance gains in dependency resolution and package installation.

The run subcommand was a natural and essential addition to uv's functionality, providing a seamless way to execute scripts and applications within the managed virtual environments. This integration makes uv a comprehensive tool for both dependency management and execution workflow, reflecting a modern approach to Python development environments.

python(1), pip(1), venv(1), virtualenv(1), pipenv(1)