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

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 files or pyproject.toml configurations for standalone utilities.

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

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

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

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, production training scripts use this pattern:

# /// 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 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 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 script includes only:

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

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 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 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, 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 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 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, the remote worker reads the same metadata block and installs the packages before execution, matching your local environment exactly.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}