# How uv-scripts Manages Single-File Python Scripts with Inline Dependencies

> Discover how uv-scripts simplifies single-file Python scripts by parsing inline dependencies, automatically resolving them and creating isolated environments without a pyproject.toml. Effortless dependency management for your P...

- Repository: [Astral/uv](https://github.com/astral-sh/uv)
- Tags: how-to-guide
- Published: 2026-03-01

---

**The `uv-scripts` crate in the `astral-sh/uv` repository implements PEP 723 to parse inline TOML metadata blocks from single-file Python scripts, enabling automatic dependency resolution and isolated environment creation without requiring a separate [`pyproject.toml`](https://github.com/astral-sh/uv/blob/main/pyproject.toml) file.**

The `uv-scripts` crate serves as the internal Rust engine that powers `uv`'s ability to treat single-file Python scripts as self-contained projects. By implementing PEP 723 (script metadata), it allows developers to declare dependencies and Python version requirements directly within a script's comments, eliminating the need for external configuration files when running standalone utilities.

## What is uv-scripts?

The `uv-scripts` crate is a core component of the `astral-sh/uv` monorepo, written in Rust to handle the complete lifecycle of single-file Python scripts that carry inline metadata. It bridges the gap between simple "single file" workflows and `uv`'s full project management capabilities by treating a script with a PEP 723 metadata block as a temporary, in-memory project.

When you execute `uv run --script my_script.py`, the `uv-scripts` crate reads the file, extracts the metadata block, and feeds the declared dependencies into `uv`'s standard resolution and installation pipeline—identical to how it handles full [`pyproject.toml`](https://github.com/astral-sh/uv/blob/main/pyproject.toml) projects.

## How Inline Dependencies Work in uv-scripts

Inline dependencies in `uv-scripts` rely on the PEP 723 specification, which defines a standardized TOML block embedded in Python script comments. The block is delimited by `# /// script` and `# ///` markers, allowing the script to declare its runtime requirements without external files.

### Parsing PEP 723 Metadata Blocks

The heavy lifting of parsing occurs in `ScriptTag::parse` within [`crates/uv-scripts/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-scripts/src/lib.rs) (lines 95-140). This function strips leading `#` characters from each line, validates the opening pragma (`# /// script`) and closing pragma (`# ///`), and extracts the TOML content between them.

The parser returns a structured representation containing the prelude (content before the block), the metadata TOML, and the postlude (content after the block), enabling `uv` to reconstruct the script if needed while processing the metadata separately.

### The Pep723Metadata Structure

Once parsed, the TOML content is deserialized into the `Pep723Metadata` structure (defined around lines 61-67 in [`lib.rs`](https://github.com/astral-sh/uv/blob/main/lib.rs)). This struct captures three critical fields:

- **`requires-python`**: A version specifier string defining the compatible Python interpreter range.
- **`dependencies`**: An array of PEP 508 dependency specifiers (e.g., `"requests>=2.28"`).
- **`tool.uv`**: An optional configuration table supporting `uv`-specific features like custom indexes, sources, and installer options.

This structure allows `uv-scripts` to feed the script's requirements directly into the existing dependency resolver, ensuring that a single-file script receives the same resolution logic as a full project.

## Running Scripts with uv run --script

When you execute `uv run --script my_script.py`, the `uv-scripts` crate orchestrates a seamless workflow that treats the script as a temporary project. The process begins with `Pep723Script::read` (lines 71-99 in [`crates/uv-scripts/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-scripts/src/lib.rs)), an async loader that extracts the metadata block from the file.

Once extracted, `uv-scripts` creates an ephemeral, in-memory project containing the declared dependencies. It then invokes `uv`'s standard resolution and installation machinery to:

1. Resolve the dependency tree against the specified Python version constraints.
2. Install the required packages into an isolated environment.
3. Execute the script with the correct interpreter and `PYTHONPATH` configured.

This approach ensures that running a single-file script with inline dependencies is as reproducible and isolated as running a full `uv` project, without leaving behind a [`pyproject.toml`](https://github.com/astral-sh/uv/blob/main/pyproject.toml) or virtual environment in the working directory.

## Creating Scripts with Inline Dependencies

The `uv-scripts` crate also supports generating new scripts with properly formatted metadata blocks through the `serialize_metadata` function (lines 334-351 in [`lib.rs`](https://github.com/astral-sh/uv/blob/main/lib.rs)). This functionality powers the `uv init --script` command, allowing developers to scaffold new executable scripts with inline dependency declarations.

When creating a script, `serialize_metadata` ensures that the TOML block is correctly formatted with the required `# /// script` prefix and `# ///` suffix, and that the content adheres to the PEP 723 specification. This guarantees that subsequent `uv run --script` commands will correctly parse the metadata without manual formatting errors.

For example, to create a new script with specific dependencies:

```bash
uv init --script my_tool.py --python 3.11

```

This generates a file containing a properly structured metadata block ready for editing, ensuring that the script will be recognized by `Pep723Script::read` when executed.

## Summary

- The `uv-scripts` crate in `astral-sh/uv` implements **PEP 723** to enable inline dependency metadata in single-file Python scripts.
- **`ScriptTag::parse`** (lines 95-140 in [`crates/uv-scripts/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-scripts/src/lib.rs)) extracts and validates TOML blocks delimited by `# /// script` markers.

- **`Pep723Metadata`** structures the parsed data, capturing `requires-python`, `dependencies`, and `tool.uv` configuration.
- **`Pep723Script::read`** creates temporary in-memory projects, allowing `uv run --script` to resolve and install dependencies in isolated environments.
- **`serialize_metadata`** (lines 334-351) supports script generation via `uv init --script`, ensuring correctly formatted metadata blocks.

## Frequently Asked Questions

### What is PEP 723 and how does uv-scripts implement it?

PEP 723 defines a standard for embedding TOML metadata within Python script comments using `# /// script` delimiters. The `uv-scripts` crate implements this through `ScriptTag::parse` in [`crates/uv-scripts/src/lib.rs`](https://github.com/astral-sh/uv/blob/main/crates/uv-scripts/src/lib.rs), which validates these blocks and deserializes them into the `Pep723Metadata` structure, enabling `uv` to treat single files as complete project definitions.

### How does uv run --script handle dependency resolution for single files?

When executing `uv run --script`, the `Pep723Script::read` function (lines 71-99) extracts the inline metadata and constructs an ephemeral, in-memory project. This project is then passed to `uv`'s standard resolver, which installs the declared dependencies into an isolated environment before executing the script, ensuring reproducibility without modifying the working directory.

### Can I use tool.uv configuration in inline script metadata?

Yes, the `Pep723Metadata` structure supports an optional `tool.uv` table that allows configuring indexes, sources, and installer options directly within the script metadata block. These settings are exposed through helper methods like `Pep723ItemRef::indexes` and are only respected when explicitly enabled, allowing the script to specify custom package sources alongside standard PEP 723 fields.

### How do I create a new script with uv init --script?

The `uv init --script` command utilizes the `serialize_metadata` function (lines 334-351 in [`lib.rs`](https://github.com/astral-sh/uv/blob/main/lib.rs)) to generate a new Python file containing a properly formatted PEP 723 metadata block. This ensures the script includes the correct `# /// script` delimiters and TOML structure, making it immediately compatible with `uv run --script` without requiring manual formatting of the inline metadata.