# Configuring PEP 723 Inline Dependencies in UV Scripts: The Complete Guide

> Learn to configure PEP 723 inline dependencies in UV scripts for automatic package installation. Master dependency management in your Python projects with this complete guide.

- Repository: [Hugging Face/skills](https://github.com/huggingface/skills)
- Tags: how-to-guide
- Published: 2026-03-08

---

**PEP 723 inline metadata lets Python scripts declare their own dependencies in a header comment block, enabling uv to automatically install packages like `trl` and `transformers` before execution.**

The `huggingface/skills` repository demonstrates production-grade patterns for managing ML script dependencies using PEP 723 inline metadata. By embedding `requires-python` and `dependencies` declarations directly in script headers, you eliminate manual environment setup while ensuring reproducible execution across local machines and remote Hugging Face Jobs.

## Understanding PEP 723 Inline Script Metadata

PEP 723 defines a standard for *inline script metadata* that allows a single Python file to specify its runtime requirements. This eliminates the need for separate [`requirements.txt`](https://github.com/huggingface/skills/blob/main/requirements.txt) files or [`pyproject.toml`](https://github.com/huggingface/skills/blob/main/pyproject.toml) configurations for standalone utilities.

The metadata block uses a TOML-like syntax enclosed in a three-line comment sandwich:

```python

# /// script

# requires-python = ">=3.10"

# dependencies = [

#   "requests>=2.28.0",

#   "numpy==1.26.4",

# ]

# ///

```

Key constraints from the specification:
- The block must start with `# /// script` and end with `# ///`

- It must appear at the very top of the file (only a shebang or encoding comment may precede it)
- `requires-python` specifies the minimum Python version using PEP 440 syntax
- `dependencies` accepts a list of PEP 508 requirement specifiers

## How UV Interprets PEP 723 Headers

When you execute a script with `uv run`, the uv runtime performs three distinct phases before your code executes:

1. **Parsing** – uv reads the first lines of the file and extracts the TOML content between the `# ///` delimiters

2. **Resolution** – uv builds a temporary lockfile in memory, resolving the exact versions of the specified packages
3. **Execution** – uv creates an isolated virtual environment, installs the wheels, caches the result, and runs the script

This process occurs once per script run, with subsequent executions benefiting from uv's aggressive caching layer. The environment is ephemeral—uv destroys the temporary venv after execution—leaving your system Python untouched.

## Configuring PEP 723 Inline Dependencies in UV Scripts

To configure dependencies for a uv script, prepend the header block to your source code. The dependencies field supports version pinning, extras, and index specifications exactly as defined in PEP 508.

### Minimal Configuration Example

```python

# /// script

# requires-python = ">=3.10"

# dependencies = [

#   "requests>=2.28.0",

#   "numpy==1.26.4",

# ]

# ///

import requests
import numpy as np

resp = requests.get("https://api.github.com")
print("GitHub status:", resp.status_code)
print("NumPy version:", np.__version__)

```

Run this locally without any prior setup:

```bash
uv run my_script.py

```

### Complex ML Workflow Configuration

For machine learning workflows requiring multiple heavy dependencies, specify the full stack in the header. According to the source code in [`skills/hugging-face-model-trainer/scripts/train_sft_example.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/train_sft_example.py), production training scripts use this pattern:

```python

# /// script

# requires-python = ">=3.10"

# dependencies = [

#   "trl>=0.12.0",

#   "peft>=0.7.0",

#   "transformers>=4.36.0",

#   "accelerate>=0.24.0",

#   "trackio",

# ]

# ///

from datasets import load_dataset
from peft import LoraConfig
from trl import SFTTrainer, SFTConfig
import trackio

```

When you invoke `uv run train_sft_example.py`, uv automatically resolves and installs **trl**, **peft**, **transformers**, **accelerate**, and **trackio** before the first import statement executes.

## Real-World Examples from the Skills Repository

The `huggingface/skills` repository uses PEP 723 headers extensively across three categories of scripts: model training, dataset management, and evaluation.

### Fine-Tuning Scripts with Heavy Dependencies

The [`skills/hugging-face-model-trainer/scripts/unsloth_sft_example.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/unsloth_sft_example.py) file demonstrates an end-to-end fine-tuning implementation with a canonical PEP 723 header spanning lines 1–4. This script declares dependencies like `trl`, `peft`, and `unsloth` to ensure the GPU-accelerated environment is provisioned automatically.

Similarly, [`skills/hugging-face-model-trainer/scripts/train_sft_example.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/scripts/train_sft_example.py) contains a production-grade SFT configuration. The header explicitly pins `trl>=0.12.0` and `transformers>=4.36.0`, guaranteeing that the supervised fine-tuning behavior matches the documentation exactly.

### Dataset Management Utilities

For lighter utilities, the repository uses minimal dependency lists. The [`skills/hugging-face-datasets/scripts/dataset_manager.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-datasets/scripts/dataset_manager.py) script includes only:

```python

# /// script

# requires-python = ">=3.10"

# dependencies = [

#   "huggingface_hub>=0.20.0",

# ]

# ///

from huggingface_hub import HfApi, create_repo

```

Executing `uv run dataset_manager.py init --repo_id user/my-dataset` installs the `huggingface_hub` client on-the-fly and immediately performs the repository creation without requiring a persistent virtual environment.

### Remote Execution via Hugging Face Jobs

The [`skills/hugging-face-jobs/SKILL.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-jobs/SKILL.md) documentation explains how the `hf_jobs` MCP tool forwards these scripts to remote workers. When submitting via `hf_jobs("uv", ...)`, the PEP 723 header travels with the script content, allowing the remote uv runtime to recreate the exact same environment.

```python
hf_jobs("uv", {
    "script": """# /// script

# requires-python = ">=3.10"

# dependencies = ["requests>=2.28.0", "numpy==1.26.4"]

# ///

import requests, numpy as np
print(requests.get("https://api.github.com").status_code)
print(np.__version__)""",
    "flavor": "a10g-small",
    "timeout": "10m",
    "secrets": {"HF_TOKEN": "$HF_TOKEN"},
})

```

The [`skills/hugging-face-model-trainer/SKILL.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/SKILL.md) file (lines 155–170) refers to this as "Approach 1: UV Scripts (Recommended)" and highlights that the `script` field can contain the entire file as an inline string, making it ideal for Claude Code and similar agentic workflows.

## Benefits for ML Workflows

Configuring PEP 723 inline dependencies in uv scripts provides four specific advantages for the Hugging Face Skills ecosystem:

- **Zero-setup execution** – Users only need the `uv` binary. No `pip install` steps or [`requirements.txt`](https://github.com/huggingface/skills/blob/main/requirements.txt) maintenance is required.
- **Deterministic reproduction** – Exact version pins (e.g., `"transformers==4.57.3"`) guarantee that CI pipelines and remote Jobs execute against identical package versions.
- **Portability** – The same file runs locally with `uv run script.py` or remotely via `hf_jobs("uv", {"script": "<code>"})` without modification.
- **Explicit error handling** – Missing or incompatible packages surface as clear uv resolution errors during the pre-execution phase, rather than cryptic import failures at runtime.

## Summary

- **PEP 723** embeds TOML metadata in Python script comments to declare `requires-python` and `dependencies` without external files.
- **uv** parses this header to create temporary, cached virtual environments automatically before script execution.
- The `huggingface/skills` repository implements this pattern in [`train_sft_example.py`](https://github.com/huggingface/skills/blob/main/train_sft_example.py), [`dataset_manager.py`](https://github.com/huggingface/skills/blob/main/dataset_manager.py), and other scripts to enable zero-setup ML workflows.
- Scripts can be executed locally with `uv run` or remotely via the `hf_jobs("uv", ...)` MCP tool, with the inline dependencies ensuring environment consistency.
- Headers must follow strict formatting: start with `# /// script`, end with `# ///`, and appear at the absolute top of the file.

## Frequently Asked Questions

### What is the exact syntax for a PEP 723 header in uv scripts?

The header must begin with `# /// script` on its own line, followed by TOML key-value pairs for `requires-python` and `dependencies`, and terminate with `# ///`. Each line inside the block must start with a `#` comment character. For example, [`skills/hugging-face-datasets/scripts/dataset_manager.py`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-datasets/scripts/dataset_manager.py) uses this exact format to declare its `huggingface_hub` dependency.

### Can I use local file paths in PEP 723 dependencies?

No. According to the [`skills/hugging-face-model-trainer/SKILL.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-model-trainer/SKILL.md) documentation, local file paths (e.g., `dependencies = ["./my_package"]`) are not supported in PEP 723 headers processed by uv. You must use package names available on PyPI or other configured indexes.

### How does uv handle caching for scripts with inline dependencies?

uv generates a lockfile based on the dependency specifiers and caches the resulting virtual environment. If the script content and dependency list remain unchanged, subsequent `uv run` invocations reuse the cached environment, providing near-instant startup times after the first resolution.

### How do I run a PEP 723 script on Hugging Face Jobs?

Use the `hf_jobs` MCP tool with the `"uv"` job type, passing the complete script content (including the PEP 723 header) in the `script` field. As shown in [`skills/hugging-face-jobs/SKILL.md`](https://github.com/huggingface/skills/blob/main/skills/hugging-face-jobs/SKILL.md), the remote worker reads the same metadata block and installs the packages before execution, matching your local environment exactly.