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.

Every Python installation has an environment for packages. uv automatically creates isolated virtual environments for scripts and prefers declarative dependencies.

Running scripts without dependencies

Execute any Python script with uv run:

example.py

print("Hello world")

uv run example.py
# Hello world

Scripts with standard library imports

No special setup needed for standard library modules:

example.py

import os

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

uv run example.py
# /Users/astral

Passing arguments

Pass arguments to your script after the script name:

example.py

import sys

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

uv run example.py hello world!
# hello world!

Reading from stdin

Pipe input

echo 'print("hello world!")' | uv run -

uv run - <<EOF
print("hello world!")
EOF

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

uv run --no-project example.py

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:

example.py

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:

uv run --with rich example.py
# For example: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:01

Add version constraints if needed:

Version constraint

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

uv run --with rich --with httpx example.py

If used in a project, --with dependencies are included in addition to project dependencies. Use --no-project to opt-out.

Declaring script dependencies

1. Initialize a script with metadata

   Create a script with inline metadata using the PEP 723 format:

   uv init --script example.py --python 3.12
   
2. Add dependencies

   Use uv add --script to declare dependencies:

   uv add --script example.py 'requests<3' 'rich'
   

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

   example.py

   # /// 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])
   
3. Run the script

   uv automatically creates an environment with the required dependencies:

   uv run example.py
   

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

Python version requirements

Specify required Python versions in the script metadata:

example.py

# /// 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:

1. Create script with shebang

   greet

   #!/usr/bin/env -S uv run --script
   
   print("Hello, world!")
   
2. Make executable

   chmod +x greet
   
3. Run directly

   ./greet
   # Hello, world!
   

Shebang with dependencies

example

#!/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:

uv add --index "https://example.com/simple" --script example.py 'requests<3' 'rich'

This includes the index in the inline metadata:

# [[tool.uv.index]]
# url = "https://example.com/simple"

Locking dependencies

Explicitly lock script dependencies:

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:

example.py

# /// script
# dependencies = [
#   "requests",
# ]
# [tool.uv]
# exclude-newer = "2023-10-16T00:00:00Z"
# ///

import requests

print(requests.__version__)

The date should be an RFC 3339 timestamp.

Using different Python versions

Request arbitrary Python versions per invocation:

example.py

import sys

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

Default version

uv run example.py
# 3.12.6

uv run --python 3.10 example.py
# 3.10.15

GUI scripts (Windows)

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

example.pyw

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()

uv run example.pyw

Works with dependencies too:

uv run --with PyQt5 example_pyqt.pyw

Complete example

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

1. Initialize the script

   uv init --script weather.py --python 3.11
   
2. Add dependencies

   uv add --script weather.py httpx rich
   
3. Write your code

   weather.py

   # /// 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())
   
4. Run the script

   uv run weather.py
   
5. Lock for reproducibility

   uv lock --script weather.py
   

Next steps

Command reference

View all uv run options

Using tools

Run and install Python tools

Python versions

Learn about Python version management

Working with projects

Manage multi-file Python projects