uv

uv — gestor de paquetes, entornos y versiones de Python.

sudo dnf install uv

Para compilar dependencias sin wheel:

sudo dnf install gcc gcc-c++ make

Config global

~/.config/uv/uv.toml:

python-preference = "only-managed"

Así uv nunca agarra el Python del sistema. Equivale a pasar --managed-python siempre.

Python

uv python list          # disponibles / instalados
uv python install 3.13
uv python pin 3.13      # escribe .python-version
uv python upgrade       # sube el patch (3.13.5 -> 3.13.6)
uv python find          # cual usaria aca
uv python uninstall 3.12

No hace falta instalar a mano: uv run y uv sync bajan el que falte.

Proyectos

uv init                 # en el directorio actual
uv init mi-proyecto     # crea el directorio
uv init --lib           # libreria (sin entry point)
uv init --no-package    # layout plano con main.py
uv init --bare          # solo pyproject.toml
uv init --python 3.13   # fija la version
uv init --vcs none      # sin git init

Desde 0.12 el default es packaged: crea src/, [build-system] con uv_build y un entry point. Se corre con uv run mi-proyecto. Con --no-package es el layout viejo (main.py), se corre con uv run main.py.

Genera .gitignore (venv, __pycache__, build) y git init. Si ya hay repo, no pisa nada.

Dependencias

uv add requests
uv add "fastapi>=0.115"
uv add --dev pytest ruff        # grupo dev
uv add --group docs mkdocs      # grupo propio
uv add -r requirements.txt
uv add "git+https://github.com/user/repo"
uv remove requests

Entorno

uv sync                 # instala lo del lockfile
uv sync --upgrade       # actualiza todo
uv sync --frozen        # sin re-resolver (CI)
uv lock                 # solo resolver
uv lock --check         # falla si esta desactualizado
uv run python main.py   # ejecuta (sincroniza antes)
uv run pytest
uv run -m modulo
uv tree                 # arbol de dependencias

.venv se crea solo. No hace falta activar nada, basta uv run.

Commitear uv.lock. Ignorar .venv.

Correr con deps extra sin instalarlas

uv run --with pandas python
uv run --isolated pytest

Jupyter

Rapido (sin proyecto)

uvx jupyter lab
uv run --with jupyter --with pandas --with matplotlib jupyter lab

Entorno efimero, no deja nada instalado.

Dentro de un proyecto

uv add --dev ipykernel
uv run --with jupyter jupyter lab

Jupyter corre aislado, pero el notebook ve las dependencias del proyecto.

Kernel propio (VS Code / Zed)

uv add --dev ipykernel
uv run ipython kernel install --user --env VIRTUAL_ENV $(pwd)/.venv --name=mi-proyecto

Despues elegirlo en el selector de kernel.

jupyter kernelspec list                 # ver kernels
jupyter kernelspec uninstall mi-proyecto

Instalar desde una celda

!uv add pandas           # persiste en pyproject.toml + uv.lock
!uv pip install pandas   # solo en el .venv, no persiste

Para usar !uv add desde el notebook hace falta uv add --dev uv.

Herramientas CLI

Equivalente a pipx, cada una en su entorno aislado.

uvx ruff check .        # ejecutar sin instalar
uvx --from httpie http example.com

uv tool install ruff
uv tool list
uv tool upgrade --all
uv tool uninstall ruff
uv tool dir             # donde viven

Scripts sueltos

Dependencias dentro del propio archivo (PEP 723).

uv init --script fetch.py --python 3.13
uv add --script fetch.py requests rich
uv run fetch.py
uv lock --script fetch.py     # crea fetch.py.lock

Queda como cabecera:

# /// script
# requires-python = ">=3.13"
# dependencies = ["requests", "rich"]
# ///

Ejecutable directo:

#!/usr/bin/env -S uv run --script

chmod +x fetch.py
./fetch.py

Interfaz pip

Para casos sueltos, sin proyecto.

uv venv                 # crea .venv
uv venv --python 3.12
uv venv --seed          # con pip/setuptools dentro
uv pip install pandas
uv pip list
uv pip freeze
uv pip compile requirements.in -o requirements.txt
uv pip sync requirements.txt

Extra

uv format               # formatear codigo del proyecto
uv check                # chequeos sobre el proyecto
uv audit                # vulnerabilidades en las dependencias
uv export --format requirements-txt > requirements.txt
uv self version
uv cache size
uv cache prune          # limpiar lo no usado
uv cache clean          # limpiar todo

Fijar la serie de uv en pyproject.toml:

[tool.uv]
required-version = ">=0.12,<0.13"

El minor rompe compatibilidad (incluido el formato de uv.lock), el patch no. Lo importante es no mezclar 0.11 y 0.12 entre maquinas.