uv-scripts

# UV Scripts

## Overview
Use `uv run` to execute standalone scripts with automatic dependency management. Prefer inline metadata for self-contained scripts and `--no-project` when you are inside a project but do not need project code.

## Quick Reference

| Need | Command |
| --- | --- |
| Run a script | `uv run script.py` |
| Run module | `uv run -m http.server 8000` |
| Run from stdin | `uv run -` |
| Here-doc | `uv run - <<EOF ... EOF` |
| Skip project install | `uv run --no-project script.py` |
| One-off deps | `uv run --with requests --with rich script.py` |
| Pick Python | `uv run --python 3.12 script.py` |
| Init script metadata | `uv init --script script.py --python 3.12` |
| Add script deps | `uv add --script script.py requests rich` |
| Lock script deps | `uv lock --script script.py` |

## Running a Script Without Dependencies

```bash
uv run example.py
uv run example.py arg1 arg2
```

Run a module:

```bash
uv run -m http.server 8000
uv run -m pytest
```

Read from stdin:

```bash
echo 'print("hello")' | uv run -
```

Here-doc:

```bash
uv run - <<EOF
print("hello")
EOF
```

## Project vs. No-Project Mode

- In a project (directory with `pyproject.toml`), `uv run` installs the project first.
- If the script does not need project code, use `--no-project` to skip installation.
- The `--no-project` flag must be before the script name.

```bash
uv run --no-project example.py
```

If you use inline script metadata, project dependencies are ignored automatically and `--no-project` is not required.

## Running a Script With Dependencies

Use `--with` to add per-invocation dependencies:

```bash
uv run --with rich example.py
uv run --with 'rich>12,<13' example.py
uv run --with rich --with requests example.py
```

In a project, these dependencies are added on top of project dependencies. Use `--no-project` to avoid that.

## Inline Script Metadata (Recommended)

Initialize inline metadata:

```bash
uv init --script example.py --python 3.12
```

Add dependencies: