> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/astral-sh/uv/llms.txt
> Use this file to discover all available pages before exploring further.

# uv run

> Run a command or script in a Python environment

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

## Usage

```bash theme={null}
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

<ParamField path="COMMAND" type="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.
</ParamField>

## Options

### Dependency Selection

<ParamField path="--extra" type="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.
</ParamField>

<ParamField path="--all-extras" flag>
  Include all optional dependencies.

  This option is only available when running in a project.
</ParamField>

<ParamField path="--no-extra" type="string[]">
  Exclude the specified optional dependencies, if `--all-extras` is supplied.

  May be provided multiple times.
</ParamField>

<ParamField path="--group" type="string[]">
  Include dependencies from the specified dependency group.

  May be provided multiple times.
</ParamField>

<ParamField path="--no-group" type="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`
</ParamField>

<ParamField path="--all-groups" flag>
  Include dependencies from all dependency groups.

  `--no-group` can be used to exclude specific groups.
</ParamField>

<ParamField path="--no-default-groups" flag>
  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`
</ParamField>

<ParamField path="--only-group" type="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`.
</ParamField>

<ParamField path="--only-dev" flag>
  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`.
</ParamField>

### Execution Mode

<ParamField path="--module" flag>
  Run a Python module.

  Equivalent to `python -m <module>`.

  Short form: `-m`
</ParamField>

<ParamField path="--script" flag>
  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`
</ParamField>

<ParamField path="--gui-script" flag>
  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.
</ParamField>

### Additional Dependencies

<ParamField path="--with" type="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`
</ParamField>

<ParamField path="--with-editable" type="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.
</ParamField>

<ParamField path="--with-requirements" type="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.
</ParamField>

### Environment Options

<ParamField path="--isolated" flag>
  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`
</ParamField>

<ParamField path="--no-editable" flag>
  Install any editable dependencies, including the project and any workspace members, as non-editable.

  Environment variable: `UV_NO_EDITABLE`
</ParamField>

<ParamField path="--inexact" flag>
  Do not remove extraneous packages present in the environment.

  By default, `uv run` will make the minimum necessary changes to satisfy the requirements.
</ParamField>

<ParamField path="--exact" flag>
  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.
</ParamField>

<ParamField path="--env-file" type="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`
</ParamField>

<ParamField path="--no-env-file" flag>
  Avoid reading environment variables from a `.env` file.

  Environment variable: `UV_NO_ENV_FILE`
</ParamField>

### Syncing Options

<ParamField path="--no-sync" flag>
  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`
</ParamField>

<ParamField path="--locked" flag>
  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`
</ParamField>

<ParamField path="--frozen" flag>
  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`
</ParamField>

### Workspace Options

<ParamField path="--all-packages" flag>
  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.
</ParamField>

<ParamField path="--package" type="string">
  Run the command in a specific package in the workspace.

  If the workspace member does not exist, uv will exit with an error.
</ParamField>

<ParamField path="--no-project" flag>
  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.
</ParamField>

### Python Options

<ParamField path="--python" type="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`
</ParamField>

<ParamField path="--python-platform" type="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.
</ParamField>

<ParamField path="--active" flag>
  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.
</ParamField>

## Examples

### Run a Python script

```bash theme={null}
uv run script.py
```

Equivalent to:

```bash theme={null}
uv run python script.py
```

### Run a Python module

```bash theme={null}
uv run --module http.server
```

Equivalent to:

```bash theme={null}
uv run python -m http.server
```

Short form:

```bash theme={null}
uv run -m http.server
```

### Run a command

```bash theme={null}
uv run pytest
```

Runs pytest in the project environment.

### Run with additional dependencies

```bash theme={null}
uv run --with requests --with beautifulsoup4 -- scraper.py
```

Runs the script with temporary additional packages installed.

### Run a PEP 723 script

```bash theme={null}
uv run script.py
```

If `script.py` contains inline metadata:

```python theme={null}
# /// 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

```bash theme={null}
uv run https://example.com/script.py
```

Downloads and runs the script.

### Run from stdin

```bash theme={null}
echo "print('Hello, World!')" | uv run -
```

### Run with specific extras

```bash theme={null}
uv run --extra dev pytest
```

Includes optional dependencies from the `dev` extra before running pytest.

### Run with all extras

```bash theme={null}
uv run --all-extras pytest
```

### Run without syncing

```bash theme={null}
uv run --no-sync script.py
```

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

### Run in isolation

```bash theme={null}
uv run --isolated pytest
```

Creates a fresh environment for this run.

### Run with environment variables

```bash theme={null}
uv run --env-file .env.local script.py
```

Loads environment variables from `.env.local` before running.

### Run with specific Python version

```bash theme={null}
uv run --python 3.11 script.py
```

## Common Patterns

### Run tests

```bash theme={null}
uv run pytest
uv run pytest tests/
uv run pytest -v --cov
```

### Run formatters and linters

```bash theme={null}
uv run black .
uv run ruff check
uv run mypy src/
```

### Run development servers

```bash theme={null}
uv run uvicorn main:app --reload
uv run flask run
uv run python -m http.server
```

### Run with development dependencies

```bash theme={null}
uv run --group dev pytest
```

### One-off scripts with dependencies

```bash theme={null}
uv run --with httpx --with rich -- python -c "
import httpx
from rich import print
print(httpx.get('https://api.github.com').json())
"
```

### Run Jupyter

```bash theme={null}
uv run --with jupyter jupyter notebook
```

### Run a script in a workspace package

```bash theme={null}
uv run --package my-package script.py
```

## Related Commands

* [`uv sync`](/cli/sync) - Sync the project environment
* [`uv add`](/cli/add) - Add dependencies to run
* [`uv init`](/cli/init) - Create a new project
* [`uv lock`](/cli/lock) - Update the lockfile