uv, pipx y metadatos en línea en scripts de Python

Un proyecto con tres paquetes necesita cuatro pasos en cada computadora en la que se ejecuta: crear un entorno, instalar en él las versiones correctas, anotar esas versiones y repetirlo todo después de cada cambio. El venv y el pip de la lección anterior hacen cada paso, y los pasos se quedan anticuados el día en que alguien olvida uno. Dos herramientas hacen esta contabilidad por ti: uv gestiona un proyecto entero, y pipx instala aplicaciones de línea de órdenes, cada una en un entorno propio.

A continuación configuras un proyecto con uv y ves qué comprueba antes de cada ejecución, comparas un rango de versiones con un archivo de bloqueo, das a un solo script su propia lista de dependencias e instalas herramientas para que nunca choquen con tus proyectos. Ninguna de las dos herramientas forma parte de Python: las dos son programas de código abierto que instalas una vez.

uv mantiene el entorno de un proyecto al día con pyproject.toml

uv, creado por Astral y con licencia MIT o Apache-2.0, es un solo programa que hace el trabajo de varios: instala versiones de Python (uv python install 3.14), crea entornos virtuales, calcula qué versiones de tus dependencias encajan entre sí, las anota y ejecuta tu código. Instálalo con un gestor de paquetes (brew install uv en macOS, winget install --id=astral-sh.uv -e en Windows), con pipx install uv o con el script de instalación de la documentación de uv. Un script que descargas y ejecutas tiene el mismo acceso a tu computadora que tú, así que míralo antes; la documentación explica cómo.

Tres órdenes ponen en marcha un proyecto:

1. uv init weather-notes crea la carpeta weather-notes con un pyproject.toml, un archivo .python-version que nombra la versión de Python que hay que usar, un README.md, un .gitignore, un repositorio de Git y código inicial en src/weather_notes/__init__.py.
2. uv add rich, en esa carpeta, escribe el requisito rich>=15.0.0, con la versión más nueva que encaja como la mínima permitida, en pyproject.toml. También crea .venv si no existe, instala rich en él y anota las versiones exactas en uv.lock.
3. uv run weather-notes ejecuta la orden que configuró uv init, y uv run some_file.py ejecuta cualquier archivo, dentro del entorno del proyecto.

Lo que hace fiable a uv run es lo que comprueba antes de ejecutar nada. Recorre una ejecución:

Así que nunca activas nada y nunca ejecutas con un conjunto de paquetes anticuado. uv remove rich vuelve a quitar una dependencia, uv sync hace que .venv coincida exactamente con uv.lock (después de traer los cambios de un compañero, por ejemplo), y uv lock --upgrade-package rich pasa un paquete a su versión permitida más nueva.

pyproject.toml no es un invento de uv: es el archivo estándar en el que un proyecto de Python se describe a sí mismo, escrito en TOMLTom's Obvious, Minimal Language, un formato de texto para configuraciones: líneas clave = valor agrupadas bajo encabezados entre corchetes., y cualquier herramienta puede leerlo. La biblioteca estándar lo lee con tomllib:

[project]
name = "weather-notes"
version = "0.1.0"
description = "Short notes about the weather"
readme = "README.md"
requires-python = ">=3.14"
dependencies = [
    "rich>=15.0.0",
]

[project.scripts]
weather-notes = "weather_notes:main"

[build-system]
requires = ["uv_build>=0.13.1,<0.14"]
build-backend = "uv_build"

import tomllib

# tomllib, in the standard library since Python 3.11, reads TOML; it needs the file opened in binary mode.
with open("pyproject.toml", "rb") as file:
    pyproject = tomllib.load(file)

project = pyproject["project"]
print("Project:", project["name"], project["version"])
print("Needs Python", project["requires-python"])
for requirement in project["dependencies"]:
    print("Depends on", requirement)
for command, target in project["scripts"].items():
    print("Adds the command", command, "which runs", target)
print("Built by", pyproject["build-system"]["build-backend"])

Project: weather-notes 0.1.0
Needs Python >=3.14
Depends on rich>=15.0.0
Adds the command weather-notes which runs weather_notes:main
Built by uv_build

La tabla [project] contiene el nombre, la versión, las versiones de Python que admite el proyecto y sus dependencias; [project.scripts] añade la orden weather-notes, y [build-system] nombra uv_build, el backend que convierte el proyecto en un paquete. Desde uv 0.12, uv init da por defecto un sistema de construcción a una aplicación.

Un archivo de bloqueo convierte rangos en un único conjunto exacto de versiones

Un requisito como rich>=15.0.0 es un especificador de versiónespecificador de versión: La parte de un requisito que dice qué versiones son aceptables, como >=1.2,<2 o ~=1.2. Las versiones se comparan número a número, y pip instala la más nueva que cumple todas las condiciones. Más en “Buscar e instalar paquetes de terceros” (en inglés), un rango: vale cualquier versión a partir de la 15.0.0. Qué versión obtienes de verdad se decide al construir el entorno, y puede cambiar de una semana a la siguiente. Este programa sigue un paquete inventado, tablekit, a través de sus versiones en las semanas 1, 5 y 9, y compara una instalación nueva desde el rango con una instalación desde el bloqueo:

# tablekit is a made-up package: the versions its index offers in three weeks.
releases = {
    1: ["2.3.0"],
    5: ["2.3.0", "2.4.0"],
    9: ["2.3.0", "2.4.0", "3.0.0"],
}
locked = "2.3.0"  # what uv.lock recorded in week 1


def as_numbers(version):
    return tuple(int(part) for part in version.split("."))


def newest_allowed(available, minimum):
    allowed = [v for v in available if as_numbers(v) >= as_numbers(minimum)]
    return max(allowed, key=as_numbers)


print("Week  tablekit>=2.3.0 gives  uv.lock gives")
for week, available in releases.items():
    print(f"{week:>4}  {newest_allowed(available, '2.3.0'):<21}  {locked}")

Week  tablekit>=2.3.0 gives  uv.lock gives
   1  2.3.0                  2.3.0
   5  2.4.0                  2.3.0
   9  3.0.0                  2.3.0

In week 9 a fresh install from the range gets 3.0.0, a new major version that may rename what your code calls, while everyone who installs from the lock still gets 2.3.0. A archivo de bloqueolock file: A file that records every package an application installs, direct and indirect, with its exact version, where each file came from and the file's hash, so the next install gets the same files. pylock.toml is the standard format. records the exact version of every package that was installed, including the dependencies of your dependencies: rich 15.0.0 itself needs markdown-it-py and Pygments, so uv.lock lists them too, each with its exact version. Press Edit, add "3.1.0" to week 9’s list and run it again: the range moves on, the lock does not.

uv guarda su bloqueo en uv.lock, que va en el control de versiones y nunca se edita a mano (la carpeta .venv, de nuevo, no se sube). Un formato estándar para los archivos de bloqueo, pylock.toml, lo define la PEP 751: uv export --format pylock.toml escribe uno, y pip 26.2.1 tiene una orden experimental pip lock que también lo escribe. El requirements.txt que escribe pip freeze es la forma más antigua y sencilla de fijar versiones, y todavía la que más se admite.

Un script puede llevar su propia lista de dependencias

Not everything is a project. A single file that you run now and then can say what it needs in a comment block at its top, called metadatos en línea del scriptinline script metadata: A comment block in a Python script, opened by # /// script and closed by # ///, whose lines hold TOML such as requires-python and dependencies. Script runners read it; Python itself ignores it., a packaging standard since PEP 723:

# /// script
# requires-python = ">=3.14"
# dependencies = [
#   "rich",
# ]
# ///
from rich import print

print("[bold green]Report ready[/bold green]")

Traceback (most recent call last):
  File "report.py", line 7, in <module>
    from rich import print
ModuleNotFoundError: No module named 'rich'

El propio Python ignora el bloque: para python3 solo son comentarios. Por eso la ejecución de arriba, con CPython 3.14.8 sin más, se detiene en la importación con ModuleNotFoundError. Una herramienta que lee el bloque lo hace mejor: uv run report.py y pipx run report.py lo leen, construyen un entorno que contiene rich y ejecutan el script en él. pipx conserva ese entorno y construye uno nuevo cuando cambia la lista de dependencias.

Las reglas son pocas. El bloque empieza con una línea que es exactamente # /// script y termina con una línea que es exactamente # ///. Todas las líneas entre ellas son comentarios: quita el # y el espacio que lo sigue, y lo que queda es TOML, con las claves requires-python (las versiones de Python en las que funciona el script) y dependencies (una lista de requisitos, como la de pyproject.toml). Un script solo puede tener un bloque script; las herramientas rechazan un archivo con dos. Recorre un programa que lee el bloque de report.py como lo hace una de esas herramientas:

import tomllib
from pathlib import Path

src = Path("report.py").read_text()
inside = False
toml = []
for line in src.splitlines():
    if line == "# /// script":
        inside = True
    elif line == "# ///":
        inside = False
    elif inside:
        toml.append(line[2:])

meta = tomllib.loads("\n".join(toml))
print("requires-python:", meta["requires-python"])
print("dependencies:", meta["dependencies"])

requires-python: >=3.14
dependencies: ['rich']

El bucle guardó las cuatro líneas entre las dos marcas, cada una sin sus dos primeros caracteres, y tomllib las convirtió en la cadena >=3.14 y la lista ['rich'].

uv también puede escribir el bloque por ti: uv init --script report.py crea un script nuevo con uno, y uv add --script report.py rich le añade una dependencia. uv espera una clave dependencies incluso cuando la lista está vacía, y un script solo se bloquea cuando lo pides, con uv lock --script report.py, que escribe report.py.lock.

pipx y uv tool dan a cada aplicación su propio entorno

Some packages are applications that you run as commands, such as the linter Ruff, rather than libraries that your code imports. Install those with pipxpipx: A tool that installs each Python application into a virtual environment of its own and links only its commands into a folder on PATH, ~/.local/bin by default. uv tool does the same job. or with uv tool: each application gets a virtual environment of its own, so its dependencies never clash with your projects or with each other, and only its commands are put on your PATH. Step through one install:

pipx viene de un gestor de paquetes (brew install pipx en macOS, sudo apt install pipx en Ubuntu, scoop install pipx en Windows) o, en Windows, de py -m pip install --user pipx. uvx es la forma corta de uv tool run. Una herramienta instalada así no la puede importar tu propio código: vive en su propio entorno, que es justo la idea. Una herramienta que tiene que importar tu proyecto, como pytest al ejecutar tus pruebas, va en el propio proyecto, como dependencia de desarrollo (uv add --dev pytest), y se ejecuta con uv run pytest.

Elige la herramienta según el trabajo

Los tres hacen por debajo los mismos pasos: un entorno virtual, una instalación, un registro de versiones. Se diferencian en cuánto hacen por ti y en para qué sirven:

Lee la tabla desde el trabajo que tienes. En una computadora del colegio en la que no puedes instalar nada más que Python, venv y pip es lo que tienes, y bastan. Un proyecto de equipo con dependencias y pruebas en cada cambio es trabajo de uv, con uv.lock en el repositorio. Un linter que usas en todas las carpetas va a pipx o a uv tool, y un script que ejecutas una vez al mes lleva su propio bloque y se ejecuta con uv run.

Nada de esto sustituye a saber usar venv y pip: uv y pipx automatizan los mismos pasos, y cuando alguno hace algo inesperado, las órdenes de la lección anterior son la forma de mirar dentro.

Practica: leer los metadatos de un script

Escribe la parte de un ejecutor de scripts que lee el bloque: devuelve su TOML como un dict, None cuando no hay bloque, y lanza ValueError para un script con dos. Las pruebas de ejemplo se ejecutan en tu navegador:

import tomllib


def parse_script_metadata(text):
    """Return the TOML of the script's '# /// script' block as a dict, or None if it has none."""
    return None

from script_meta import parse_script_metadata

BLOCK = """# /// script
# requires-python = ">=3.14"
# dependencies = [
#   "rich",
# ]
# ///
print("Report ready")
"""


def test_one_block():
    """reads the TOML of the block"""
    assert parse_script_metadata(BLOCK) == {"requires-python": ">=3.14", "dependencies": ["rich"]}


def test_no_block():
    """gives None for a script without a block"""
    assert parse_script_metadata('print("Report ready")\n') is None


def test_two_blocks():
    """refuses a script with two script blocks"""
    try:
        parse_script_metadata(BLOCK + BLOCK)
    except ValueError:
        return
    raise AssertionError("a script with two script blocks must raise ValueError")


def test_empty_dependencies():
    """reads a block whose dependencies list is empty"""
    assert parse_script_metadata("# /// script\n# dependencies = []\n# ///\n") == {"dependencies": []}


def test_line_of_only_a_hash():
    """treats a line that is only # as an empty line of the block"""
    text = '# /// script\n# requires-python = ">=3.14"\n#\n# dependencies = []\n# ///\n'
    assert parse_script_metadata(text) == {"requires-python": ">=3.14", "dependencies": []}

Termina con las preguntas de abajo, que siguen tus respuestas: un fallo trae una pregunta más sencilla sobre la misma idea, y cada opción lleva su propia explicación:

Preguntas de entrevista

Calentamiento (júnior): ¿qué diferencia hay entre pyproject.toml y uv.lock?

pyproject.toml es la descripción propia del proyecto, el archivo que editas: su nombre y su versión, las versiones de Python que admite y sus dependencias como rangos, como rich>=15.0.0, que dicen qué sería aceptable. uv.lock lo escribe uv: la versión exacta de cada paquete que instala el proyecto, incluidas las dependencias de sus dependencias, para que todas las computadoras y todas las instalaciones posteriores obtengan el mismo conjunto. pyproject.toml lo cambias tú o con uv add, y uv.lock nunca se edita a mano; los dos se suben al repositorio. Cuando quieras versiones más nuevas, actualizas el bloqueo a propósito, con uv lock --upgrade-package, y pruebas el resultado antes de subirlo.

Dos preguntas más difíciles parten de esta lección: una compilación que se rompió durante un fin de semana sin ningún cambio de código, y un equipo con sus herramientas instaladas en sitios equivocados. Piensa tu primer paso antes de abrir cada una:

Para recordar

• uv gestiona un proyecto desde pyproject.toml: uv init, uv add y uv run, y antes de cada ejecución comprueba que uv.lock y .venv están al día.
• pyproject.toml contiene rangos de versiones aceptables; uv.lock anota un conjunto exacto, dependencias incluidas, y se sube al repositorio para que todo el mundo instale los mismos paquetes.
• Los metadatos en línea de un script son un bloque de comentarios # /// script con requires-python y dependencies; uv run y pipx run lo leen, mientras que un python3 sin más lo ignora.
• pipx install y uv tool install dan a cada aplicación de línea de órdenes su propio entorno y ponen solo sus órdenes en tu PATH; las herramientas que importan tu proyecto van en el proyecto.
• uv y pipx automatizan los pasos de venv y pip, que siguen funcionando en cualquier computadora.