¿Por qué usar el modo proyecto?#

• Sin activar entornos: uv run sincroniza y ejecuta en un solo paso.
• Reproducibilidad real: uv.lock guarda la versión exacta de todas las dependencias, incluidas las indirectas.
• Un solo comando para replicar: quien clone tu proyecto solo necesita ejecutar uv sync.
• Gestión de Python incluida: uv descarga la versión de Python que el proyecto necesite.

uv pip vs modo proyecto#

Inicializar#

1
uv init mi_proyecto
2
cd mi_proyecto

O, si ya estás dentro de la carpeta:

1
uv init

¿Qué se crea?#

1
mi_proyecto/
2
├── .git/
3
├── .gitignore
4
├── .python-version   # Versión de Python del proyecto
5
├── README.md
6
├── main.py           # Script de ejemplo
7
└── pyproject.toml    # Metadatos y dependencias

El pyproject.toml inicial luce así:

1
[project]
2
name = "mi_proyecto"
3
version = "0.1.0"
4
description = "Add your description here"
5
readme = "README.md"
6
requires-python = ">=3.12"
7
dependencies = []

TIP

El .venv y el uv.lock no se crean con uv init. Aparecen la primera vez que ejecutas uv add, uv sync o uv run.

Elegir la versión de Python#

1
# Al crear el proyecto
2
uv init mi_proyecto --python 3.12
3

4
# En un proyecto existente
5
uv python pin 3.12

Si no tienes esa versión instalada, uv la descarga automáticamente.

Añadir paquetes#

1
uv add requests
2

3
# Con versión específica
4
uv add requests==2.32.3
5

6
# Con un rango de versiones
7
uv add "requests>=2.31,<3"

Cada uv add actualiza tres cosas a la vez: el pyproject.toml, el uv.lock y el .venv.

Dependencias de desarrollo#

Paquetes que solo necesitas mientras desarrollas (tests, linters, etc.):

1
uv add --dev pytest ruff

Eliminar paquetes#

1
uv remove requests

Ver el árbol de dependencias#

1
uv tree

Con uv run#

1
uv run main.py
2
uv run python -c "import requests; print(requests.__version__)"
3
uv run pytest

Antes de ejecutar, uv run comprueba que el entorno esté sincronizado con el uv.lock. Si falta algo, lo instala. Por eso no hace falta activar nada.

Activando el entorno (si lo prefieres)#

El modo proyecto sigue usando un .venv normal, así que el alias del post anterior sigue funcionando:

1
echo "alias uvs='source .venv/bin/activate'" >> ~/.bashrc

1
source .venv/bin/activate

Instalar sin dependencias de desarrollo#

Útil para servidores o contenedores:

1
uv sync --no-dev

Fallar si el lock no está al día#

Útil en CI, para asegurarte de que nadie olvidó actualizar el uv.lock:

1
uv sync --locked

Importar#

1
uv init
2
uv add -r requirements.txt

Exportar#

Si alguien necesita un requirements.txt (por ejemplo, una herramienta que no soporta uv):

1
uv export --format requirements-txt > requirements.txt

Ejemplo Frida y Objection#

El mismo ejemplo del UV Cheatsheet, ahora en modo proyecto:

1
# Creamos el proyecto
2
uv init 16.5.2 && cd 16.5.2
3

4
# Añadimos las herramientas que necesitamos
5
uv add frida==16.5.2 frida-tools objection==1.11.0
6

7
# Corroboramos que todo funcione
8
uv run frida --version
9
# 16.5.2
10

11
# Ejemplo con un script
12
# uv run frida -U -f com.app.app -l script.js

TIP

Al fijar frida==16.5.2, uv elige automáticamente una versión de frida-tools compatible con ella. Con pip, a veces terminas con una versión de frida-tools que pide otra versión de frida.

Ejemplo xcat con una versión específica de Python#

1
# Creamos el proyecto con Python 3.10
2
uv init xcat_uv --python 3.10 && cd xcat_uv
3

4
# Añadimos xcat
5
uv add xcat
6

7
# Corroboramos que todo funcione
8
uv run xcat --version

NOTE

Si solo quieres usar una herramienta de línea de comandos (como xcat) y no vas a escribir código alrededor de ella, uv tool es más cómodo:

1
uv tool install xcat --python 3.10
2
xcat --version