uv run - uv

Run a command or script, ensuring it executes in a Python environment.

Usage

uv run [OPTIONS] [COMMAND]

Description

Ensures that the command runs in a Python environment. When used with a file ending in .py or an HTTP(S) URL, the file will be treated as a script and run with a Python interpreter (i.e., uv run file.py is equivalent to uv run python file.py). For URLs, the script is temporarily downloaded before execution. If the script contains inline dependency metadata, it will be installed into an isolated, ephemeral environment. When used with -, the input will be read from stdin and treated as a Python script. When used in a project, the project environment will be created and updated before invoking the command. When used outside a project, if a virtual environment can be found in the current directory or a parent directory, the command will be run in that environment. Otherwise, the command will be run in the environment of the discovered interpreter. By default, the project or workspace is discovered from the current working directory. However, when using --preview-features target-workspace-discovery, the project or workspace is instead discovered from the target script’s directory. Arguments following the command (or script) are not interpreted as arguments to uv. All options to uv must be provided before the command, e.g., uv run --verbose foo. A -- can be used to separate the command from uv options for clarity, e.g., uv run --python 3.12 -- python.

Arguments

COMMAND

string

The command to run.If the path to a Python script (i.e., ending in .py), it will be executed with the Python interpreter.

Options

Dependency Selection

--extra

string[]

Include optional dependencies from the specified extra name.May be provided more than once.This option is only available when running in a project.

--all-extras

Include all optional dependencies.This option is only available when running in a project.

--no-extra

string[]

Exclude the specified optional dependencies, if --all-extras is supplied.May be provided multiple times.

--group

string[]

Include dependencies from the specified dependency group.May be provided multiple times.

--no-group

string[]

Disable the specified dependency group.This option always takes precedence over default groups, --all-groups, and --group.May be provided multiple times.Environment variable: UV_NO_GROUP

--all-groups

Include dependencies from all dependency groups.--no-group can be used to exclude specific groups.

--no-default-groups

Ignore the default dependency groups.uv includes the groups defined in tool.uv.default-groups by default. This disables that option, however, specific groups can still be included with --group.Environment variable: UV_NO_DEFAULT_GROUPS

--only-group

string[]

Only include dependencies from the specified dependency group.The project and its dependencies will be omitted.May be provided multiple times. Implies --no-default-groups.

--only-dev

Only include the development dependency group.The project and its dependencies will be omitted.This option is an alias for --only-group dev. Implies --no-default-groups.

Execution Mode

--module

Run a Python module.Equivalent to python -m <module>.Short form: -m

--script

Run the given path as a Python script.Using --script will attempt to parse the path as a PEP 723 script, irrespective of its extension.Short form: -s

--gui-script

Run the given path as a Python GUI script.Using --gui-script will attempt to parse the path as a PEP 723 script and run it with pythonw.exe, irrespective of its extension. Only available on Windows.

Additional Dependencies

--with

string[]

Run with the given packages installed.When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.Short form: -w

--with-editable

string[]

Run with the given packages installed in editable mode.When used in a project, these dependencies will be layered on top of the project environment in a separate, ephemeral environment. These dependencies are allowed to conflict with those specified by the project.

--with-requirements

path[]

Run with the packages listed in the given files.The following formats are supported: requirements.txt, .py files with inline metadata, and pylock.toml.The same environment semantics as --with apply.Using pyproject.toml, setup.py, or setup.cfg files is not allowed.

Environment Options

--isolated

Run the command in an isolated virtual environment.Usually, the project environment is reused for performance. This option forces a fresh environment to be used for the project, enforcing strict isolation between dependencies and declaration of requirements.An editable installation is still used for the project.When used with --with or --with-requirements, the additional dependencies will still be layered in a second environment.Environment variable: UV_ISOLATED

--no-editable

Install any editable dependencies, including the project and any workspace members, as non-editable.Environment variable: UV_NO_EDITABLE

--inexact

Do not remove extraneous packages present in the environment.By default, uv run will make the minimum necessary changes to satisfy the requirements.

--exact

Perform an exact sync, removing extraneous packages.When enabled, uv will remove any extraneous packages from the environment. By default, uv run will make the minimum necessary changes to satisfy the requirements.

--env-file

path[]

Load environment variables from a .env file.Can be provided multiple times, with subsequent files overriding values defined in previous files.Environment variable: UV_ENV_FILE

--no-env-file

Avoid reading environment variables from a .env file.Environment variable: UV_NO_ENV_FILE

Syncing Options

--no-sync

Avoid syncing the virtual environment.Implies --frozen, as the project dependencies will be ignored (i.e., the lockfile will not be updated, since the environment will not be synced regardless).Environment variable: UV_NO_SYNC

--locked

Assert that the uv.lock will remain unchanged.Requires that the lockfile is up-to-date. If the lockfile is missing or needs to be updated, uv will exit with an error.Environment variable: UV_LOCKED

--frozen

Run without updating the uv.lock file.Instead of checking if the lockfile is up-to-date, uses the versions in the lockfile as the source of truth. If the lockfile is missing, uv will exit with an error. If the pyproject.toml includes changes to dependencies that have not been included in the lockfile yet, they will not be present in the environment.Environment variable: UV_FROZEN

Workspace Options

--all-packages

Run the command with all workspace members installed.The workspace’s environment (.venv) is updated to include all workspace members.Any extras or groups specified via --extra, --group, or related options will be applied to all workspace members.

--package

string

Run the command in a specific package in the workspace.If the workspace member does not exist, uv will exit with an error.

--no-project

Avoid discovering the project or workspace.Instead of searching for projects in the current directory and parent directories, run in an isolated, ephemeral environment populated by the --with requirements.If a virtual environment is active or found in a current or parent directory, it will be used as if there was no project or workspace.

Python Options

--python

string

The Python interpreter to use for the run environment.If the interpreter request is satisfied by a discovered environment, the environment will be used.See uv help python for details on Python discovery and supported request formats.Short form: -p
Environment variable: UV_PYTHON

--python-platform

string

The platform for which requirements should be installed.Represented as a “target triple”, a string that describes the target platform in terms of its CPU, vendor, and operating system name, like x86_64-unknown-linux-gnu or aarch64-apple-darwin.WARNING: When specified, uv will select wheels that are compatible with the target platform.

--active

Prefer the active virtual environment over the project’s virtual environment.If the project virtual environment is active or no virtual environment is active, this has no effect.

Examples

Run a Python script

uv run script.py

Equivalent to:

uv run python script.py

Run a Python module

uv run --module http.server

Equivalent to:

uv run python -m http.server

Short form:

uv run -m http.server

Run a command

uv run pytest

Runs pytest in the project environment.

Run with additional dependencies

uv run --with requests --with beautifulsoup4 -- scraper.py

Runs the script with temporary additional packages installed.

Run a PEP 723 script

uv run script.py

If script.py contains inline metadata:

# /// script
# dependencies = [
#   "requests",
#   "beautifulsoup4",
# ]
# requires-python = ">=3.11"
# ///

import requests
from bs4 import BeautifulSoup

uv will automatically create an ephemeral environment with the specified dependencies.

Run a script from a URL

uv run https://example.com/script.py

Downloads and runs the script.

Run from stdin

echo "print('Hello, World!')" | uv run -

Run with specific extras

uv run --extra dev pytest

Includes optional dependencies from the dev extra before running pytest.

Run with all extras

uv run --all-extras pytest

Run without syncing

uv run --no-sync script.py

Runs the script without updating the environment first (uses existing environment as-is).

Run in isolation

uv run --isolated pytest

Creates a fresh environment for this run.

Run with environment variables

uv run --env-file .env.local script.py

Loads environment variables from .env.local before running.

Run with specific Python version

uv run --python 3.11 script.py

Common Patterns

Run tests

uv run pytest
uv run pytest tests/
uv run pytest -v --cov

Run formatters and linters

uv run black .
uv run ruff check
uv run mypy src/

Run development servers

uv run uvicorn main:app --reload
uv run flask run
uv run python -m http.server

Run with development dependencies

uv run --group dev pytest

One-off scripts with dependencies

uv run --with httpx --with rich -- python -c "
import httpx
from rich import print
print(httpx.get('https://api.github.com').json())
"

Run Jupyter

uv run --with jupyter jupyter notebook

Run a script in a workspace package

uv run --package my-package script.py

uv sync - Sync the project environment
uv add - Add dependencies to run
uv init - Create a new project
uv lock - Update the lockfile

Overview

Project Commands

Python Management

Tool Commands

Pip Interface

Build & Publish

Environment

Cache & Maintenance

​Usage

​Description

​Arguments

​Options

​Dependency Selection

​Execution Mode

​Additional Dependencies

​Environment Options

​Syncing Options

​Workspace Options

​Python Options

​Examples

​Run a Python script

​Run a Python module

​Run a command

​Run with additional dependencies

​Run a PEP 723 script

​Run a script from a URL

​Run from stdin

​Run with specific extras

​Run with all extras

​Run without syncing

​Run in isolation

​Run with environment variables

​Run with specific Python version

​Common Patterns

​Run tests

​Run formatters and linters

​Run development servers

​Run with development dependencies

​One-off scripts with dependencies

​Run Jupyter

​Run a script in a workspace package

​Related Commands

Build docs developers (and LLMs) love

Usage

Description

Arguments

Options

Dependency Selection

Execution Mode

Additional Dependencies

Environment Options

Syncing Options

Workspace Options

Python Options

Examples

Run a Python script

Run a Python module

Run a command

Run with additional dependencies

Run a PEP 723 script

Run a script from a URL

Run from stdin

Run with specific extras

Run with all extras

Run without syncing

Run in isolation

Run with environment variables

Run with specific Python version

Common Patterns

Run tests

Run formatters and linters

Run development servers

Run with development dependencies

One-off scripts with dependencies

Run Jupyter

Run a script in a workspace package

Related Commands