Skip to main content

​
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

echo 'print("hello world!")' | uv run -
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: 
uv run --with 'rich>12,<13' 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])))

uv run example.py
# 3.12.6

​
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

Build docs developers (and LLMs) love

Get started for freeTalk to us