> ## 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.

# Running Scripts

> Execute Python scripts with inline dependencies and reproducible environments

## Overview

Python scripts are single files intended for standalone execution. uv manages script dependencies automatically without requiring manual environment management.

<Note>
  Every Python installation has an environment for packages. uv automatically creates isolated [virtual environments](https://docs.python.org/3/library/venv.html) for scripts and prefers declarative dependencies.
</Note>

## Running scripts without dependencies

Execute any Python script with `uv run`:

```python example.py theme={null}
print("Hello world")
```

```bash theme={null}
uv run example.py
# Hello world
```

### Scripts with standard library imports

No special setup needed for standard library modules:

```python example.py theme={null}
import os

print(os.path.expanduser("~"))
```

```bash theme={null}
uv run example.py
# /Users/astral
```

### Passing arguments

Pass arguments to your script after the script name:

```python example.py theme={null}
import sys

print(" ".join(sys.argv[1:]))
```

```bash theme={null}
uv run example.py hello world!
# hello world!
```

### Reading from stdin

<CodeGroup>
  ```bash Pipe input theme={null}
  echo 'print("hello world!")' | uv run -
  ```

  ```bash Here-document theme={null}
  uv run - <<EOF
  print("hello world!")
  EOF
  ```
</CodeGroup>

<Tip>
  If you use `uv run` in a project directory (with `pyproject.toml`), use `--no-project` to skip installing the project:

  ```bash theme={null}
  uv run --no-project example.py
  ```
</Tip>

## Running scripts with dependencies

When your script requires external packages, declare dependencies explicitly. uv creates environments on-demand instead of using long-lived virtual environments.

### Requesting dependencies per invocation

For a script requiring `rich`:

```python example.py theme={null}
import time
from rich.progress import track

for i in track(range(20), description="For example:"):
    time.sleep(0.05)
```

Request the dependency with `--with`:

```bash theme={null}
uv run --with rich example.py
# For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01
```

Add version constraints if needed:

<CodeGroup>
  ```bash Version constraint theme={null}
  uv run --with 'rich>12,<13' example.py
  ```

  ```bash Multiple dependencies theme={null}
  uv run --with rich --with httpx example.py
  ```
</CodeGroup>

<Note>
  If used in a project, `--with` dependencies are included *in addition* to project dependencies. Use `--no-project` to opt-out.
</Note>

## Declaring script dependencies

<Steps>
  <Step title="Initialize a script with metadata">
    Create a script with inline metadata using the [PEP 723](https://packaging.python.org/en/latest/specifications/inline-script-metadata/) format:

    ```bash theme={null}
    uv init --script example.py --python 3.12
    ```
  </Step>

  <Step title="Add dependencies">
    Use `uv add --script` to declare dependencies:

    ```bash theme={null}
    uv add --script example.py 'requests<3' 'rich'
    ```

    This adds a `script` section at the top of your file:

    ```python example.py theme={null}
    # /// script
    # dependencies = [
    #   "requests<3",
    #   "rich",
    # ]
    # ///

    import requests
    from rich.pretty import pprint

    resp = requests.get("https://peps.python.org/api/peps.json")
    data = resp.json()
    pprint([(k, v["title"]) for k, v in data.items()][:10])
    ```
  </Step>

  <Step title="Run the script">
    uv automatically creates an environment with the required dependencies:

    ```bash theme={null}
    uv run example.py
    ```
  </Step>
</Steps>

<Warning>
  When using inline script metadata, the `dependencies` field must be provided even if empty. Project dependencies are ignored — no `--no-project` flag needed.
</Warning>

### Python version requirements

Specify required Python versions in the script metadata:

```python example.py theme={null}
# /// script
# requires-python = ">=3.12"
# dependencies = []
# ///

# Use Python 3.12+ syntax
type Point = tuple[float, float]
print(Point)
```

uv will search for and download the required Python version if it's not installed.

## Using a shebang for executable scripts

Make scripts executable without `uv run`:

<Steps>
  <Step title="Create script with shebang">
    ```python greet theme={null}
    #!/usr/bin/env -S uv run --script

    print("Hello, world!")
    ```
  </Step>

  <Step title="Make executable">
    ```bash theme={null}
    chmod +x greet
    ```
  </Step>

  <Step title="Run directly">
    ```bash theme={null}
    ./greet
    # Hello, world!
    ```
  </Step>
</Steps>

### Shebang with dependencies

```python example theme={null}
#!/usr/bin/env -S uv run --script
#
# /// script
# requires-python = ">=3.12"
# dependencies = ["httpx"]
# ///

import httpx

print(httpx.get("https://example.com"))
```

## Advanced features

### Using alternative package indexes

Specify a custom package index:

```bash theme={null}
uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich'
```

This includes the index in the inline metadata:

```python theme={null}
# [[tool.uv.index]]
# url = "https://example.com/simple"
```

### Locking dependencies

Explicitly lock script dependencies:

```bash theme={null}
uv lock --script example.py
```

This creates `example.py.lock` adjacent to your script. Subsequent operations reuse the locked dependencies.

### Improving reproducibility

Limit packages to those released before a specific date:

```python example.py theme={null}
# /// script
# dependencies = [
#   "requests",
# ]
# [tool.uv]
# exclude-newer = "2023-10-16T00:00:00Z"
# ///

import requests

print(requests.__version__)
```

The date should be an [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339.html) timestamp.

### Using different Python versions

Request arbitrary Python versions per invocation:

```python example.py theme={null}
import sys

print(".".join(map(str, sys.version_info[:3])))
```

<CodeGroup>
  ```bash Default version theme={null}
  uv run example.py
  # 3.12.6
  ```

  ```bash Specific version theme={null}
  uv run --python 3.10 example.py
  # 3.10.15
  ```
</CodeGroup>

### GUI scripts (Windows)

On Windows, scripts with `.pyw` extension run using `pythonw`:

```python example.pyw theme={null}
from tkinter import Tk, ttk

root = Tk()
root.title("uv")
frm = ttk.Frame(root, padding=10)
frm.grid()
ttk.Label(frm, text="Hello World").grid(column=0, row=0)
root.mainloop()
```

```powershell theme={null}
uv run example.pyw
```

Works with dependencies too:

```powershell theme={null}
uv run --with PyQt5 example_pyqt.pyw
```

## Complete example

Here's a complete workflow for creating a self-contained script:

<Steps>
  <Step title="Initialize the script">
    ```bash theme={null}
    uv init --script weather.py --python 3.11
    ```
  </Step>

  <Step title="Add dependencies">
    ```bash theme={null}
    uv add --script weather.py httpx rich
    ```
  </Step>

  <Step title="Write your code">
    ```python weather.py theme={null}
    # /// script
    # requires-python = ">=3.11"
    # dependencies = [
    #   "httpx",
    #   "rich",
    # ]
    # ///

    import httpx
    from rich.console import Console

    console = Console()
    response = httpx.get("https://api.weather.gov/")
    console.print(response.json())
    ```
  </Step>

  <Step title="Run the script">
    ```bash theme={null}
    uv run weather.py
    ```
  </Step>

  <Step title="Lock for reproducibility">
    ```bash theme={null}
    uv lock --script weather.py
    ```
  </Step>
</Steps>

## Next steps

<CardGroup cols={2}>
  <Card title="Command reference" icon="terminal" href="../reference/cli.md#uv-run">
    View all uv run options
  </Card>

  <Card title="Using tools" icon="wrench" href="./tools.mdx">
    Run and install Python tools
  </Card>

  <Card title="Python versions" icon="snake" href="../concepts/python-versions.md">
    Learn about Python version management
  </Card>

  <Card title="Working with projects" icon="folder" href="./projects.mdx">
    Manage multi-file Python projects
  </Card>
</CardGroup>