uv-script

Write self-contained Python scripts with PEP 723 metadata for uv execution.

1|Updated May 22, 2013
One-click install
npx skills add https://github.com/scottopell/dotfiles --skill uv-script-scottopell
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: uv-script
Source: https://github.com/scottopell/dotfiles/tree/main/home-dir-configs/claude/skills/uv-script
Command: npx skills add https://github.com/scottopell/dotfiles --skill uv-script-scottopell

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Write self-contained Python scripts that run with uv without requiring a virtual environment or external dependencies, enabling quick automation and tooling on any machine.

Core Features & Use Cases

  • Inline PEP 723 metadata blocks declare dependencies and Python version, enabling reproducible, self-contained scripts.
  • Deterministic, no-setup execution: scripts run directly with uv, without a virtualenv or requirements.txt.
  • Use Case: build small CLIs, one-off automation tasks, or helpers that rely on third-party packages while staying portable.

Quick Start

Create a Python script with the uv shebang and an inline PEP 723 metadata block, then chmod +x script.py and run it.

Frequently Asked Questions about uv-script

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I run a Python script with third-party dependencies without setting up a virtual environment?

You can run a Python script without a virtual environment by using uv with an inline PEP 723 metadata block that declares dependencies. This allows uv to resolve and execute the script directly, eliminating the need for manual environment setup or a requirements.txt file.

What is the best way to distribute single-file Python CLI tools that require external packages?

The best way to distribute single-file Python CLI tools is using uv with PEP 723 inline metadata. By adding a uv-friendly shebang and declaring dependencies inline, the script becomes self-contained and portable across different systems without needing external package installations.

How does inline metadata in a Python script work with uv?

Inline metadata works with uv by using a PEP 723 block to specify requires-python and dependencies directly inside the script. When executed, uv reads this block, automatically fetches the required packages, and runs the script in an isolated environment.

Can I use uv to run one-off automation scripts that rely on specific Python versions?

Yes, you can use uv for one-off automation scripts by declaring the required version in the PEP 723 inline metadata block. The requires-python field ensures uv uses the correct Python interpreter, making your automation scripts reproducible across machines.

Do I need to install dependencies globally to run a portable Python script with uv?

No, you do not need to install dependencies globally. uv reads the dependencies from the script's inline PEP 723 metadata block and handles the resolution automatically in an ephemeral environment, keeping your system clean while allowing the script to run directly.

When should I not use single-file Python scripts with uv for automation?

You should avoid single-file uv scripts when building large, multi-file applications with complex dependency trees or shared internal modules. This approach is designed for quick CLIs, one-off automation tasks, and small tools, not for replacing structured project environments.