SenseiTeoría desde cero0/59

6 · Herramientas del oficioLección 2 de 6

Python, paquetes y entornos

Python, packages and environments

De dónde saca Python el código que importa, cómo se instala el código de otros, cómo se fija la versión exacta que llega a producción y por qué una imagen con PyTorch pesa gigas.

⏱ 58 min lo esencial · 74 min todo17 conceptos nuevos2 calculadoras10 ejerciciosModelo y Contenedor
Secciones14
  1. 01Módulos, paquetes e import
  2. 02La biblioteca estándar, PyPI y pip
  3. 03Wheels y extensiones nativas
  4. 04Dependencias y versiones
  5. 05Lo que pides y lo que instalas: pyproject.toml y el lock file
  6. 06Entornos virtuales
  7. 07uv y conda: otros gestores extra
  8. 08Type hints y pydantic: tipos que se revisan y que no extra
  9. 09Errores comunes
  10. 10En la vida real extra
  11. 11Ejercicios
  12. 12Lo que sigue
  13. 13Palabras que vas a oír
  14. 14Chequeo
La pregunta

El gateway de Alba funciona en la laptop de quien lo escribió y en el contenedor truena con «ModuleNotFoundError», o corre con otra versión de NumPy. ¿De dónde saca Python el código que importa y cómo se asegura que a producción llegue exactamente lo que probaste?

Alba, la empresa que seguimos en todo el curso, es un marketplace: recibe ≈ 2.5 millones de publicaciones al día y, por cada foto, le sugiere a quien vende una categoría entre 500 posibles. Con ≈ 3 fotos por publicación (≈ 7.5 millones) más las que piden otros equipos, como moderación y búsqueda, su servicio responde ≈ 10 millones de fotos al día. Cada foto entra por el gateway, un servidor escrito en Python que la recibe, la prepara y se la pasa al modelo.

Imagina al equipo de Alba el día que arma el contenedor del gateway. En la laptop de quien lo escribió, uvicorn app.main:app, el comando que arranca su servidor, funciona sin problema. En el contenedor, la primera línea falla:

ModuleNotFoundError: No module named 'numpy'

NumPy es la librería de Python para arreglos de números, y el gateway la usa para armar el tensor de la foto. El error dice que, dentro del contenedor, Python no la encuentra.

O peor: arranca, responde, y las categorías salen un poco distintas a las de la laptop, sin un solo error. Detrás de las dos fallas hay las mismas cuatro preguntas: ¿de dónde saca Python el código que importa? ¿Cómo se instala el código de otros? ¿Cómo se fija qué versión exacta va a producción? ¿Y por qué una imagen con PyTorch pesa gigas mientras la del gateway pesa menos de 100 MB? (La imagen es el paquete congelado del que nace cada contenedor; la sección de entornos virtuales la abre por dentro.)

En la lección de la terminal viste el PATH y las variables de entorno; en «Programas y procesos», que Python es un intérprete. Con eso basta para empezar.

01

Módulos, paquetes e import

Esencial

Modules, packages and import

Python lee tu archivo .py y lo ejecuta línea por línea. Cuando tu programa crece, lo partes en varios archivos, y cada uno puede usar lo que definen los otros con import.

Un módulo (module) es un archivo .py. Su nombre es el del archivo sin la extensión: preprocess.py es el módulo preprocess, y otro archivo lo usa con import preprocess.

Un paquete (package) es una carpeta de módulos, normalmente con un archivo __init__.py adentro. El gateway de Alba es uno:

gateway/
  app/
    __init__.py      ← hace de app un paquete
    main.py          ← el módulo app.main: crea el servidor
    preprocess.py    ← el módulo app.preprocess: decodifica y redimensiona

Los puntos del nombre son carpetas: from app.preprocess import preprocess quiere decir «en la carpeta app, el archivo preprocess.py, la función preprocess». Por eso el gateway arranca con uvicorn app.main:app: «del módulo app.main, el objeto app».

Qué hace import

import json hace tres cosas:

  1. 1

    Busca

    Recorre una lista de carpetas, en orden, hasta encontrar un json.py o una carpeta json/ con su __init__.py.

  2. 2

    Ejecuta

    Corre ese archivo de arriba abajo, una sola vez. Todo lo que define (funciones, constantes) queda en un objeto módulo.

  3. 3

    Recuerda

    Guarda el módulo en sys.modules, un diccionario de los módulos ya cargados. Si otro archivo vuelve a importar json, recibe el mismo objeto sin volver a correrlo.

Si recorre toda la lista sin encontrarlo, truena con ModuleNotFoundError. Es la falla del contenedor de arriba: NumPy no estaba en ninguna de esas carpetas.

La primera vez que importas un módulo, Python además guarda una versión ya traducida en un archivo .pyc, dentro de una carpeta __pycache__, para arrancar más rápido la próxima vez. Si ves esas carpetas junto a tu código, no las escribiste tú: si las borras, se vuelven a crear solas.

Correr un módulo por su nombre

python -m nombre busca el módulo nombre igual que import, en las mismas carpetas, y lo corre como programa. Lo vas a ver en toda la lección: python -m pip, python -m venv, python -m zipfile. También sirve con la biblioteca estándar: python -m json.tool datos.json imprime un JSON con sangría, fácil de leer.

¿Cómo sabe un archivo si lo importaron o si lo corrieron? Python le pone a cada módulo su nombre en la variable __name__: el del módulo si lo importaron, y "__main__" si es el programa que arrancó. Por eso muchos archivos terminan con if __name__ == "__main__":. Lo de adentro corre solo cuando el archivo es el programa, no cuando otro lo importa.

sys.path: la lista de carpetas

La lista está en sys.path, y su orden importa porque gana el primero que aparece:

  1. La carpeta del script que corriste (o la carpeta actual, si escribes en la consola o usas python -c).
  2. Las carpetas de la variable PYTHONPATH, si existe.
  3. La biblioteca estándar, lo que trae Python, con su carpeta lib-dynload de piezas compiladas.
  4. site-packages, donde se instalan los paquetes de otros.

Así se ve en un contenedor con la imagen oficial de Python 3.13, la misma familia que usa el gateway. Son tres comandos. El primero imprime sys.path, una carpeta por línea. El segundo le pasa a python - (el guion quiere decir «lee el programa de la entrada») un programa de varias líneas, con el heredoc <<'PY' de la lección de la terminal; ese programa pregunta dónde encontraría import cinco módulos, sin ejecutarlos. El tercero intenta importar NumPy y deja solo la última línea del error:

Terminal
python -c "import sys; print(*sys.path[1:], sep='\n')"     # el [0] es '': la carpeta actual
python - <<'PY'
import importlib.util
for nombre in ("sys", "json", "math", "pytest", "numpy"):
    spec = importlib.util.find_spec(nombre)                # busca como import, sin ejecutar
    print(f"{nombre:>6}:", spec.origin if spec else "no está en ninguna carpeta")
PY
python -c "import numpy" 2>&1 | tail -1
Salida
/usr/local/lib/python313.zip
/usr/local/lib/python3.13
/usr/local/lib/python3.13/lib-dynload
/usr/local/lib/python3.13/site-packages
   sys: built-in
  json: /usr/local/lib/python3.13/json/__init__.py
  math: /usr/local/lib/python3.13/lib-dynload/math.cpython-313-aarch64-linux-gnu.so
pytest: /usr/local/lib/python3.13/site-packages/pytest/__init__.py
 numpy: no está en ninguna carpeta
ModuleNotFoundError: No module named 'numpy'

sys viene dentro del intérprete mismo (built-in). json es una carpeta de la biblioteca estándar. math es un archivo .so: código compilado, como verás en la sección de wheels; el aarch64 dice que este contenedor corrió en un chip ARM, y en una máquina Intel o AMD diría x86_64. pytest está en site-packages porque alguien lo instaló. Y numpy no está.

Cómo busca import json en las carpetas de sys.path. Las carpetas se revisan de arriba abajo y gana la primera que tenga un json. Primero, la carpeta del script, /home/ana/trabajo: si ahí hay un json.py tuyo, ese gana, se ejecuta, y la búsqueda termina. Segundo, las carpetas de PYTHONPATH, si existe la variable. Tercero, la biblioteca estándar, /usr/local/lib/python3.13, donde está el json de verdad, la carpeta json con su __init__.py: con tu json.py en la carpeta del script, nunca se lee. Cuarto, site-packages, donde se instalan los paquetes de otros, como pytest. Sin tu json.py, la búsqueda sigue de largo por la carpeta del script y por PYTHONPATH y se queda en la biblioteca estándar. IMPORT JSON: GANA EL PRIMERO import json revisa de arriba abajo 1 Carpeta del script /home/ana/trabajo json.py este gana 2 PYTHONPATH solo si existe la variable 3 Biblioteca estándar /usr/local/lib/python3.13 json/ nunca se lee 4 site-packages los paquetes de otros, como pytest Sin tu json.py, sigue de largo y se queda en el 3.
import json recorre las carpetas de sys.path de arriba abajo y se queda con el primer json que encuentra. Si tu carpeta tiene un json.py, ese gana y el de la biblioteca estándar nunca se lee.

Un archivo tuyo puede tapar a uno de Python

Como la carpeta del script va primero, un archivo tuyo llamado json.py, random.py o torch.py tapa al de verdad: import json carga el tuyo. El programa no falla al importar; falla después, cuando busca algo que tu archivo no tiene.

El modo aislado de Python, python -I, no pone la carpeta del script en sys.path (e ignora PYTHONPATH). Todos los bloques de Python de este curso se comprueban así, para que un archivo suelto no se meta. Este código arma una carpeta temporal con un json.py falso y corre el mismo programa de las dos maneras:

Python
import subprocess, sys, tempfile
from pathlib import Path

carpeta = Path(tempfile.mkdtemp())
(carpeta / "json.py").write_text('print("  (se ejecutó el json.py de tu carpeta)")\n')
(carpeta / "app.py").write_text(
    "import json\n"
    "origen = 'tu carpeta' if json.__file__.endswith('json.py') else 'la biblioteca estándar'\n"
    "print('  json viene de', origen, '· ¿tiene dumps?', hasattr(json, 'dumps'))\n")

for modo in ([], ["-I"]):
    print("python", *modo, "app.py", flush=True)
    subprocess.run([sys.executable, *modo, "app.py"], cwd=carpeta)
Salida
python app.py
  (se ejecutó el json.py de tu carpeta)
  json viene de tu carpeta · ¿tiene dumps? False
python -I app.py
  json viene de la biblioteca estándar · ¿tiene dumps? True

Sin -I, cualquier json.dumps del programa fallaría con un AttributeError (el error de «este objeto no tiene nada con ese nombre»), que no menciona el archivo culpable. La regla: no le pongas a tus archivos el nombre de un módulo que uses, y cuando algo raro pase, imprime modulo.__file__ para ver de dónde salió.

02

La biblioteca estándar, PyPI y pip

Esencial

The standard library, PyPI and pip

Lo que trae Python sin instalar nada

Una biblioteca (library; en México también se dice librería) es código que otros escribieron para que tu programa lo use. Python trae la suya: la biblioteca estándar (standard library), ≈ 200 módulos que llegan con cualquier instalación. Python 3.13 enumera 192 nombres públicos, sin contar los internos que empiezan con guion bajo. Por eso se dice que Python viene «con pilas incluidas» (batteries included).

Ya usaste muchos en este curso: json, math, struct, hashlib, sqlite3, asyncio, http.server. Casi todos los ejemplos del curso se quedan ahí a propósito: así los corres sin instalar nada.

Lo demás se instala aparte: NumPy (arreglos de números), Pillow (imágenes), FastAPI (el servidor web del gateway), PyTorch. Son paquetes de terceros: no los escribió el equipo de Python, y cada uno tiene su propio ritmo de versiones.

PyPI: el índice público

Un índice de paquetes (package index) es un servidor que guarda paquetes para que un instalador los baje. PyPI (Python Package Index, en pypi.org) es el índice público de Python: un servidor con cientos de miles de proyectos (≈ 940,000 en noviembre de 2026), cada uno con todas sus versiones y sus archivos. Cualquiera puede crear una cuenta y subir un paquete: eso lo hace enorme y también riesgoso, porque un paquete con un nombre parecido al de uno famoso puede traer código malicioso. Ese riesgo es parte de la cadena de suministro, que tiene su lección más adelante.

pip: el instalador

pip es el programa que baja paquetes de PyPI y los copia en site-packages. Viene con Python. Sus comandos de todos los días:

ComandoQué hace
pip install pillow==12.3.0Baja esa versión exacta y lo que ella pida
pip install -r requirements.txtInstala todo lo que dice un archivo, una línea por paquete
pip listLista lo instalado, en una tabla
pip freezeLo mismo, como nombre==versión: el formato de requirements.txt
pip show pillowLa ficha de un paquete: versión, qué pide, dónde quedó
pip uninstall pillowLo quita

En una máquina puede haber varios Pythons: el del sistema operativo, uno de Homebrew (un instalador de programas para la Mac), el de cada entorno virtual. El comando pip es el primero que la shell encuentra en el PATH, y puede ser de otro Python que el que corre tu programa. El paquete se instala, import falla, y nada lo explica. Por eso se recomienda python -m pip: corre el pip de ese Python, el mismo que luego hará el import.

Terminal
which python pip
python -m pip --version
python -m pip list
Salida
/usr/local/bin/python
/usr/local/bin/pip
pip 26.2.2 from /usr/local/lib/python3.13/site-packages/pip (python 3.13)
Package   Version
--------- -------
iniconfig 2.3.1
packaging 26.3
pip       26.2.2
pluggy    1.7.0
Pygments  2.21.0
pytest    8.4.2
PyYAML    6.0.3

which dice qué programa corre la shell para cada nombre, y --version dice de qué Python es ese pip: (python 3.13). Los bloques bash de esta lección corren en un contenedor de prueba sin red; en la siguiente sección instalamos de una carpeta local.

«Paquete» quiere decir dos cosas

Lo que se instala de PyPI también se llama paquete (más exacto: distribución), y su nombre no siempre es el del paquete que se importa:

Se instala con pipSe importa con
pillowimport PIL
scikit-learnimport sklearn
opencv-pythonimport cv2
PyYAMLimport yaml
tritonclient[http]import tritonclient.http

Por eso pip install PIL no sirve y import pillow da ModuleNotFoundError. Lo de los corchetes, [http], es un extra: una parte opcional del paquete que trae sus propias dependencias.

pip le pregunta a PyPI si no le dices otra cosa. Muchas empresas le dan, en cambio, su propio índice: un espejo (mirror) con copias revisadas de PyPI.

Para ir más hondoNo todo sale de PyPI: espejos y confusión de dependencias

pip pregunta por omisión a PyPI, pero se le puede dar otro índice con --index-url, o uno más con --extra-index-url. Las empresas suelen tener un índice propio: un espejo (mirror) que guarda copias revisadas de lo que se usa de PyPI, más los paquetes internos que no son públicos. Así la construcción de la imagen no depende de que PyPI responda, y nadie instala nada sin revisar.

Mezclar índices tiene una trampa. Si tu empresa tiene un paquete interno llamado alba-utils y alguien publica en PyPI otro alba-utils con una versión más alta, pip con --extra-index-url puede preferir el público. Se llama confusión de dependencias (dependency confusion), y es pariente del typosquatting, el de los nombres casi iguales a los famosos. Los dos tienen su lugar en la lección «Ataques y cadena de suministro».

03

Wheels y extensiones nativas

Esencial

Wheels and native extensions

¿Qué baja pip, exactamente? Un archivo por paquete, de una de dos clases.

La wheel: un zip ya armado

Una wheel (archivo .whl, «rueda») es un zip (un archivo comprimido que guarda muchos archivos adentro) con los archivos del paquete ya listos para copiar a site-packages, más una carpeta .dist-info con su ficha: el nombre, la versión y lo que pide. Instalarla es, en lo esencial, descomprimirla: no hace falta ningún compilador.

La otra clase es el sdist (source distribution, un .tar.gz con el código fuente). Para instalarlo, pip tiene que construirlo primero: correr la herramienta de empaquetado del proyecto y, si trae código en C, un compilador como gcc. Es lento, pide herramientas que una imagen chica no tiene y puede fallar a la mitad. Por eso el Dockerfile del gateway (la receta con que se arma su imagen) instala con --only-binary=:all:: si a algún paquete le falta su wheel, el build (el proceso que arma la imagen) falla ahí, en vez de compilar en silencio.

Como una wheel es solo un zip, se puede armar a mano. Este bloque crea dos paquetes de juguete, recorte y colores (recorte pide colores 2.0 o más nuevo), mira uno por dentro y los instala desde una carpeta local, sin internet. El script rueda.py recibe como argumentos el nombre, la versión y lo que pide, y escribe un zip con los cuatro archivos mínimos de una wheel. cut -c1-40 solo recorta cada línea a 40 letras:

Terminal
mkdir ruedas
cat > rueda.py <<'PY'
import sys, zipfile                     # arma una wheel de juguete: python rueda.py NOMBRE VERSION [LO QUE PIDE...]
nombre, version, *pide = sys.argv[1:]
info = f"{nombre}-{version}.dist-info"
meta = f"Metadata-Version: 2.1\nName: {nombre}\nVersion: {version}\n"
meta += "".join(f"Requires-Dist: {p}\n" for p in pide)
archivos = {f"{nombre}/__init__.py": f"VERSION = '{version}'\n", f"{info}/METADATA": meta,
            f"{info}/WHEEL": "Wheel-Version: 1.0\nRoot-Is-Purelib: true\nTag: py3-none-any\n", f"{info}/RECORD": ""}
with zipfile.ZipFile(f"ruedas/{nombre}-{version}-py3-none-any.whl", "w") as z:
    for ruta, texto in archivos.items():
        z.writestr(zipfile.ZipInfo(ruta, (2026, 1, 1, 0, 0, 0)), texto)
PY
python rueda.py recorte 1.0.0 "colores>=2.0"
python rueda.py colores 2.1.0
python -m zipfile -l ruedas/recorte-1.0.0-py3-none-any.whl | cut -c1-40
python -m venv .venv && source .venv/bin/activate         # un entorno limpio (sección 6)
python -m pip install --no-index --find-links ruedas recorte
python -m pip freeze
Salida
File Name
recorte/__init__.py
recorte-1.0.0.dist-info/METADATA
recorte-1.0.0.dist-info/WHEEL
recorte-1.0.0.dist-info/RECORD
Looking in links: ruedas
Processing ./ruedas/recorte-1.0.0-py3-none-any.whl
Processing ./ruedas/colores-2.1.0-py3-none-any.whl (from recorte)
Installing collected packages: colores, recorte

Successfully installed colores-2.1.0 recorte-1.0.0
colores==2.1.0
recorte==1.0.0

Pediste un paquete y llegaron dos: pip leyó el Requires-Dist de recorte y fue por colores. --no-index le prohíbe ir a PyPI y --find-links le dice dónde buscar. Las wheels de verdad traen además, en RECORD, el hash de cada archivo: su huella, que cambia si cambia un solo byte.

El nombre de una wheel dice dónde sirve

El nombre de una wheel no es libre: dice para qué Python y qué máquina se armó.

Las cinco partes del nombre de la wheel numpy-2.5.3-cp313-cp313-manylinux_2_28_x86_64.whl, separadas por guiones. Primera, numpy: el nombre del paquete. Segunda, 2.5.3: la versión. Las tres últimas son la etiqueta, que dice dónde sirve: cp313, el Python con que se compiló, CPython 3.13; cp313 otra vez, la interfaz binaria, la de CPython 3.13; y manylinux_2_28_x86_64, el sistema y el chip: Linux con glibc 2.28 o más nueva, en un chip x86_64. Abajo, una wheel de puro Python, fastapi-0.141.1-py3-none-any.whl: py3 quiere decir cualquier Python 3, none que no depende de ninguna interfaz binaria de Python (aquí, porque no trae código compilado), y any que sirve en cualquier sistema y cualquier chip. EL NOMBRE DE UNA WHEEL numpy-2.5.3-cp313-cp313- manylinux_2_28_x86_64.whl Cinco partes, separadas por guiones: numpy el nombre del paquete 2.5.3 la versión LA ETIQUETA: DÓNDE SIRVE cp313 Python: CPython 3.13 cp313 interfaz binaria: la de 3.13 manylinux_2_28_x86_64 sistema y chip Linux con glibc 2.28 o más nueva, chip x86_64 PURO PYTHON fastapi-0.141.1-py3-none-any.whl py3 cualquier Python 3 none no depende de ninguna interfaz binaria any cualquier sistema y chip Sirve en todos lados.
Las cinco partes del nombre de una wheel de NumPy. Las tres últimas son la etiqueta: con qué Python se compiló, con qué interfaz binaria y para qué sistema y chip. Una wheel de puro Python dice py3-none-any: sirve en cualquier lado.
  • py3-none-any: puro Python. Sirve en cualquier Python 3, cualquier sistema y cualquier chip. FastAPI es así.
  • cp313-cp313: compilada para CPython 3.13 (CPython es el intérprete normal de Python, el escrito en C). El primer cp313 dice con qué Python; el segundo, con qué interfaz binaria (ABI, application binary interface): las reglas de cómo el código ya compilado se conecta con el intérprete que está corriendo, qué funciones suyas llama y cómo acomoda los datos en memoria. Esas reglas cambian entre la 3.12 y la 3.13, así que esta wheel no sirve en la 3.12.
  • manylinux_2_28_x86_64: para Linux con glibc 2.28 o más nueva en un chip x86_64. glibc es la biblioteca básica de C de casi todas las distribuciones de Linux: la que usa cualquier programa compilado para abrir archivos o pedir memoria. Las imágenes python:3.13-slim son Debian y tienen glibc. (Los nombres de esta sección están simplificados: la wheel real de NumPy para Linux lleva dos etiquetas pegadas, manylinux_2_27_x86_64.manylinux_2_28_x86_64.)
  • macosx_14_0_arm64: para macOS 14 o más nuevo en un chip de Apple, como el de una MacBook.
  • musllinux_1_2_x86_64: para Linux con musl, otra biblioteca de C más chica, en vez de glibc. La usa Alpine, una distribución de Linux mínima, popular en contenedores. Muchos paquetes de ML, PyTorch entre ellos, no publican estas.

El chip es la arquitectura de CPU de «El sistema operativo». pip compara cada etiqueta con la de tu máquina y escoge la más específica que sirva:

Python
ruedas = [
    "fastapi-0.141.1-py3-none-any.whl",
    "numpy-2.5.3-cp313-cp313-manylinux_2_28_x86_64.whl",
    "numpy-2.5.3-cp313-cp313-macosx_14_0_arm64.whl",
    "numpy-2.5.3-cp312-cp312-manylinux_2_28_x86_64.whl",
    "numpy-2.5.3-cp313-cp313-musllinux_1_2_x86_64.whl",
]

def sirve(rueda, python="cp313", plataforma=("manylinux", "x86_64")):
    nombre, version, py, abi, plat = rueda.removesuffix(".whl").split("-")
    if plat == "any":                             # puro Python: sirve en todos lados
        return py.startswith("py3")
    return py == python and all(p in plat for p in plataforma)

print("En el contenedor del gateway (Linux x86_64 con glibc, Python 3.13):")
for r in ruedas:
    print(f"  {'sí' if sirve(r) else 'no'}  {r}")
Salida
En el contenedor del gateway (Linux x86_64 con glibc, Python 3.13):
  sí  fastapi-0.141.1-py3-none-any.whl
  sí  numpy-2.5.3-cp313-cp313-manylinux_2_28_x86_64.whl
  no  numpy-2.5.3-cp313-cp313-macosx_14_0_arm64.whl
  no  numpy-2.5.3-cp312-cp312-manylinux_2_28_x86_64.whl
  no  numpy-2.5.3-cp313-cp313-musllinux_1_2_x86_64.whl

Es una versión simplificada: pip también acepta wheels de glibc más viejas que la tuya, entre otros detalles.

Extensiones nativas: código compilado dentro de un paquete

¿Por qué NumPy necesita una wheel por plataforma y FastAPI no? Porque NumPy trae una extensión nativa (native extension): un módulo escrito en C, C++, Rust o CUDA y ya compilado a instrucciones de una CPU, en un archivo .so en Linux y macOS o .pyd en Windows. Python lo importa como a cualquier módulo, pero adentro no hay Python: es el math.cpython-313-aarch64-linux-gnu.so que viste arriba.

Existen por velocidad. En «CPU y GPU» viste que Python puro hace las cuentas de una en una; NumPy, Pillow y PyTorch hacen el trabajo pesado en C y C++, y pueden soltar el GIL mientras tanto. Pillow trae además librerías de imágenes compiladas, como las de JPEG; pydantic_core, el corazón de pydantic (una librería que revisa datos; la verás en la sección de type hints), está escrito en Rust, otro lenguaje que se compila; PyTorch trae C++ y kernels de CUDA. De los 37 paquetes que instala el gateway (los vas a contar en la sección que sigue), 17 traen código compilado en su wheel de Linux.

El precio: el mismo numpy==2.5.3 son archivos distintos en tu Mac y en el contenedor. Casi siempre se portan igual, pero no son el mismo binario, y a veces se nota.

PyTorch: el paquete que pesa gigas

PyTorch es el caso extremo. En Linux, pip install torch baja de PyPI una wheel que trae CUDA como dependencias: unos quince paquetes nvidia-* con las librerías de NVIDIA, más triton, un compilador de kernels (nada que ver con Triton, el servidor que corre el modelo de Alba). Para torch 2.14 (septiembre de 2026) en Linux x86_64, la wheel de solo CPU pesa ≈ 196 MB; la de PyPI, ≈ 555 MB, y con sus librerías de CUDA, ≈ 3 GB en total. Por eso una imagen con PyTorch y CUDA pesa gigas.

Las wheels nvidia-* dicen py3-none-manylinux…: traen código compilado, pero no se atan a ningún Python (none), así que una sirve en cualquier 3.x.

PyTorch tiene además su propio índice, con una variante por versión de CUDA: torch 2.14 ofrece CUDA 12.6, 13.0 y 13.2. Es una ilustración, sin salida, porque necesita internet:

Terminal
pip install torch==2.14.0 --index-url https://download.pytorch.org/whl/cu126   # con CUDA 12.6
pip install torch==2.14.0 --index-url https://download.pytorch.org/whl/cpu     # solo CPU

El CUDA de la wheel tiene que ser compatible con el driver de la máquina: la torch 2.14 de PyPI trae CUDA 13.0, que pide un driver 580 o más nuevo. Si el driver es más viejo, torch.cuda.is_available(), la función que pregunta si hay una GPU que PyTorch pueda usar, dice False y todo corre en CPU, con apenas un aviso (warning) que es fácil no ver.

De pip install a un paquete que se puede importar · Lo que pasa entre pip install y un import que funciona. Toca cada caja o usa «Recorrer» para seguir una instalación normal, una sin wheel y una con lock y hashes.
  • Índice de paquetes · wheels y sdists
    PyPI, o el espejo propio de la empresa con --index-url. Guarda, de cada paquete, todas sus versiones y sus archivos: varias wheels, una por plataforma, y a veces un sdist con el código fuente.
  • pip install · python -m pip
    Lo que pides, por ejemplo python -m pip install pillow==12.3.0. Con python -m pip corre el pip de ese Python, el mismo que después hará el import.
  • Resolvedor · elige las versiones
    La parte de pip que busca una versión de cada paquete que cumpla todas las reglas, incluidas las de las transitivas, que lee del Requires-Dist de cada ficha. Si dos reglas chocan, regresa y prueba otra versión; si no hay salida, se rinde con ResolutionImpossible.
  • Lock con hashes · requirements.txt
    El lock file: todo el árbol con == y el sha256 de cada archivo. Con él, el resolvedor no tiene nada que escoger: cada versión ya está fija. El del gateway trae las 37.
  • Construir el sdist · con un compilador
    Si no hay wheel para tu plataforma, pip baja el código fuente y lo construye: corre la herramienta de empaquetado y, si trae C, un compilador como gcc. Es lento, pide herramientas que una imagen slim no tiene y puede fallar a la mitad.
  • Escoger el archivo · por la etiqueta
    De la versión elegida, pip escoge la wheel cuya etiqueta sirve en esta máquina: Python, interfaz binaria, sistema y chip, como cp313-cp313-manylinux_2_28_x86_64. Una de puro Python, py3-none-any, sirve en todos lados.
  • Comparar el hash · --require-hashes
    Con --require-hashes, pip calcula el sha256 del archivo bajado y lo compara con el del lock. Si cambió un solo byte, se niega a instalar: THESE PACKAGES DO NOT MATCH THE HASHES.
  • site-packages · listo para import
    Instalar una wheel es descomprimirla aquí, con su carpeta .dist-info. site-packages está en sys.path, así que desde ahora import lo encuentra. Si usas un entorno virtual, es el site-packages del entorno.
04

Dependencias y versiones

Esencial

Dependencies and versions

Lo que pides y lo que eso pide

Una dependencia (dependency) es un paquete que tu código necesita para correr. El gateway importa FastAPI: FastAPI es su dependencia. Pero FastAPI, a su vez, necesita Starlette (la parte que habla HTTP) y Pydantic (la que valida datos), y Pydantic necesita pydantic_core. Esas son dependencias transitivas (transitive dependencies): las que llegan porque las pide algo que tú pediste, en cualquier nivel.

Los paquetes del gateway de AlbaLa cuenta
Directaslas que importa app/: fastapi, uvicorn, uvloop, httptools, pillow, numpy, tritonclient, aiohttp, prometheus-client
—
9
Transitivaslas que llegaron solas: starlette, pydantic, anyio, h11, yarl…
37 − 9
28
Total en el requirements.txt
9 + 28
37
Transitivas por cada directa
28 ÷ 9
≈ 3.1
Resultado
Tres de cada cuatro paquetes del gateway (28 de 37, ≈ 76 %) nadie los pidió por su nombre. Igual corren en producción, y cualquiera puede cambiar.
Una parte del árbol de dependencias del gateway de Alba. A la izquierda, cuatro de las 9 dependencias que el equipo pidió, y debajo de cada una lo que ella pide. fastapi pide starlette, que pide anyio, que pide idna; y fastapi pide también pydantic, que pide pydantic-core. uvicorn pide h11. aiohttp pide yarl, que pide idna y multidict, y aiohttp pide también multidict directamente. pillow no pide nada: su código compilado viene adentro. idna cuelga de dos ramas, la de fastapi y la de aiohttp, y multidict de dos lugares, aiohttp y yarl. A la derecha, el site-packages: cada paquete aparece una sola vez, idna y multidict incluidos, porque en un site-packages cabe una versión de cada uno. UNA PARTE DEL ÁRBOL DEL GATEWAY la pidió el equipo cuelga de dos lados fastapi starlette anyio idna pydantic pydantic-core uvicorn h11 aiohttp yarl idna multidict multidict pillow no pide nada SITE-PACKAGES cada uno, una vez aiohttp anyio fastapi h11 idna multidict pillow pydantic pydantic-core starlette uvicorn yarl
Una parte del árbol del gateway. En azul, cuatro de las 9 que el equipo pidió; colgando de cada una, algunas de las 28 que llegaron solas. Los de naranja, idna y multidict, cuelgan de dos ramas, pero en site-packages, a la derecha, cada paquete aparece una sola vez.

Cada paquete instalado guarda su ficha en su carpeta .dist-info, y la biblioteca estándar la lee con importlib.metadata. Este programa recorre el árbol de pytest en el contenedor de prueba. Usa packaging, la librería que pip usa por dentro para leer versiones; aquí ya viene, porque pytest la pide:

Terminal
python - <<'PY'
from importlib.metadata import requires, version
from packaging.requirements import Requirement

print([t for t in requires("pytest") if "win32" in t])      # una dependencia con condición

def arbol(nombre, nivel=0):
    print("  " * nivel + f"{nombre} {version(nombre)}")
    for texto in requires(nombre) or []:
        r = Requirement(texto)
        if r.marker is None or r.marker.evaluate({"extra": ""}):   # solo lo que aplica aquí
            arbol(r.name, nivel + 1)

arbol("pytest")
PY
Salida
['colorama>=0.4; sys_platform == "win32"']
pytest 8.4.2
  iniconfig 2.3.1
  packaging 26.3
  pluggy 1.7.0
  pygments 2.21.0

Lo que va después del ; es una condición (marker): pytest pide colorama solo en Windows. Por eso el árbol cambia según la plataforma, y una lista hecha en una Mac puede no servir tal cual en Linux.

Cuando dos paquetes no se ponen de acuerdo

En un site-packages cabe una versión de cada paquete. Si una dependencia pide colores>=2.0 y otra colores<2, no hay versión que deje contentas a las dos: es un conflicto de dependencias. pip lo detecta antes de instalar:

Terminal
mkdir ruedas
cat > rueda.py <<'PY'
import sys, zipfile                     # el mismo rueda.py de la sección de wheels
nombre, version, *pide = sys.argv[1:]
info = f"{nombre}-{version}.dist-info"
meta = f"Metadata-Version: 2.1\nName: {nombre}\nVersion: {version}\n"
meta += "".join(f"Requires-Dist: {p}\n" for p in pide)
archivos = {f"{nombre}/__init__.py": f"VERSION = '{version}'\n", f"{info}/METADATA": meta,
            f"{info}/WHEEL": "Wheel-Version: 1.0\nRoot-Is-Purelib: true\nTag: py3-none-any\n", f"{info}/RECORD": ""}
with zipfile.ZipFile(f"ruedas/{nombre}-{version}-py3-none-any.whl", "w") as z:
    for ruta, texto in archivos.items():
        z.writestr(zipfile.ZipInfo(ruta, (2026, 1, 1, 0, 0, 0)), texto)
PY
python rueda.py recorte 1.0.0 "colores>=2.0"
python rueda.py marco 3.2.0 "colores<2"
python rueda.py colores 2.1.0
python rueda.py colores 1.4.0
python -m venv .venv && source .venv/bin/activate
pip install --no-index --find-links ruedas recorte marco 2>&1 | grep "caused\|depends\|ResolutionImpossible" | cut -c1-55
Salida
The conflict is caused by:
    recorte 1.0.0 depends on colores>=2.0
    marco 3.2.0 depends on colores<2
ERROR: ResolutionImpossible: for help visit https://pip

La parte de pip que busca una combinación que cumpla todo se llama resolvedor (resolver); el de ahora llegó con pip 20.3, en 2020. Empieza por la versión más nueva de cada paquete que cabe en lo pedido; si más abajo del árbol eso choca con otra regla, regresa y prueba una versión anterior (backtracking). Con árboles grandes eso puede tardar minutos, y pip avisa «This could take a while».

Aquí se rinde, y hace bien: instalar cualquiera de las dos versiones de colores rompería a alguien. La salida es aflojar un rango, cambiar la versión de recorte o de marco, o quitar uno de los dos.

Qué promete cada número

Casi todos los paquetes numeran sus versiones con la idea del versionado semántico (semantic versioning, o semver): MAYOR.MENOR.PARCHE, como 2.5.3.

Sube…PrometeDe 2.5.3 a…
PARCHESolo arregla errores; nada cambia por fuera2.5.4
MENORAgrega cosas sin romper lo que había2.6.0
MAYORPuede romper: algo que funcionaba deja de funcionar3.0.0

¿Qué tanto se cumple? Es una promesa, no una regla que alguien revise:

  • Las 0.x no prometen nada. En semver, una versión 0.algo puede romper en cualquier subida. FastAPI lleva años en 0.x: el gateway usa la 0.141.
  • No todos usan semver. pip (26.2), certifi (2026.7.22) y attrs (26.1.0) numeran por fecha: el primer número es el año.
  • Una MAYOR rompe de verdad. NumPy 2.0 (2024) cambió su interfaz binaria: las extensiones compiladas contra NumPy 1.x dejaron de cargar con NumPy 2, con un error que empieza con «A module that was compiled using NumPy 1.x cannot be run in NumPy 2…».
  • Un arreglo también cambia resultados. El equipo de Alba lo tiene anotado: otra versión de Pillow puede redimensionar un poco distinto, y el accuracy baja un par de puntos sin un solo error. Es el training-serving skew de la lección de imágenes.

Cómo se escribe qué versiones aceptas

Las reglas para pedir versiones salen del PEP 440 (los PEP son los documentos donde la comunidad de Python acuerda cada cambio):

  • ==2.5.3: exactamente esa.
  • >=2.5: esa o cualquiera más nueva, incluida la 3.0.
  • <3 o !=2.5.0: un tope o una versión vetada; se combinan con coma: >=2,<3.
  • ~=2.5.3: «compatible»: 2.5.3 o más nueva, pero sin salir de la 2.5. ~=2.5 no sale de la 2.
Terminal
python - <<'PY'
from packaging.specifiers import SpecifierSet
versiones = ["1.26.4", "2.0.0", "2.5.2", "2.5.3", "2.5.4", "2.6.0", "3.0.0"]
for regla in ["==2.5.3", ">=2.5", "~=2.5.3", "~=2.5", ">=2,<3"]:
    print(f"{regla:>8} acepta:", ", ".join(SpecifierSet(regla).filter(versiones)))
PY
Salida
 ==2.5.3 acepta: 2.5.3
   >=2.5 acepta: 2.5.2, 2.5.3, 2.5.4, 2.6.0, 3.0.0
 ~=2.5.3 acepta: 2.5.3, 2.5.4
   ~=2.5 acepta: 2.5.2, 2.5.3, 2.5.4, 2.6.0
  >=2,<3 acepta: 2.0.0, 2.5.2, 2.5.3, 2.5.4, 2.6.0

Fíjate en >=2.5: acepta la 3.0.0, la que puede romper. Un rango sin tope es una apuesta a que nadie publique una MAYOR.

05

Lo que pides y lo que instalas: pyproject.toml y el lock file

Esencial

What you ask for and what you install: pyproject.toml and the lock file

Hay dos listas distintas, y confundirlas causa la mitad de los «en mi máquina sí funciona».

pyproject.toml: lo que pides

pyproject.toml es la ficha de un proyecto de Python, en la raíz de su carpeta. Está escrito en TOML, un formato de texto de llaves y valores parecido al YAML, y la biblioteca estándar lo lee con tomllib. Dice cómo se llama el proyecto, su versión, qué Python necesita, de qué depende y cómo se configuran sus herramientas, como pytest. Este es un pyproject.toml de ejemplo para el gateway (el de Alba, en realidad, usa solo requirements.txt):

Python
import tomllib                       # lee TOML; viene con Python desde la 3.11

pyproject = tomllib.loads('''
[project]
name = "gateway-alba"
version = "1.4.0"
requires-python = ">=3.13"
dependencies = ["fastapi>=0.141", "uvicorn>=0.54", "pillow==12.3.0", "numpy>=2.5,<3"]

[project.optional-dependencies]
dev = ["pytest>=9.1"]
''')

proyecto = pyproject["project"]
print(proyecto["name"], proyecto["version"], "· Python", proyecto["requires-python"])
for dep in proyecto["dependencies"]:
    print("  pide:", dep)
print("  y para los tests:", *proyecto["optional-dependencies"]["dev"])
Salida
gateway-alba 1.4.0 · Python >=3.13
  pide: fastapi>=0.141
  pide: uvicorn>=0.54
  pide: pillow==12.3.0
  pide: numpy>=2.5,<3
  y para los tests: pytest>=9.1

Son solo las directas, y casi todas con rango: «cualquier FastAPI 0.141 o más nueva». Pillow va fija porque el preprocesamiento del entrenamiento depende de ella. El rango es lo correcto aquí: dice qué versiones aceptas. Pero no dice cuáles vas a recibir: el resolvedor escoge, el día que instalas, las más nuevas que quepan. Mañana pueden ser otras.

¿Qué tan seguido pasa? Piensa en reconstruir la imagen del mismo commit (una versión guardada del código; la lección de Git lo presenta) un mes después. Si cada paquete tiene 90 % de quedarse igual, que se queden igual los 37 a la vez es multiplicar 0.9 por sí mismo 37 veces, suponiendo que cada uno cambia por su lado. En general:

Reconstruir sin lock
Pigual=(1−f)k×m
Pcambia=1−Pigual
donde
k
cuántos paquetes hay en el árbol, directos y transitivos
f
la probabilidad de que un paquete saque, en un mes, una versión nueva que cabe en su rango (0.10 = 10 %)
m
cuántos meses pasan entre el primer build y el nuevo
Pigual
la probabilidad de que no cambie ningún paquete
Pcambia
la probabilidad de que cambie al menos uno
Reconstruir el mismo commit sin lock, un mes despuésLa cuenta
Paquetes en el árbol, klas 37 del gateway
—
37
Probabilidad por paquete en un mes, fun supuesto para el ejemplo
—
10 %
Meses, m
—
1
Que no cambie ninguno, Pigual1−f = 0.9, multiplicado por sí mismo k×m = 37 veces
Pigual=(1−f)k×m = 0.9³⁷
≈ 2 %
Que cambie al menos uno, Pcambia
Pcambia=1−Pigual = 1 − 0.020
≈ 98 %
Resultado
Con solo rangos, reconstruir el mismo código un mes después casi seguro instala algo distinto. Con un lock, la probabilidad es 0: se instalan los mismos archivos, con el mismo hash.
Reconstruir sin lock: ¿qué tan probable es que algo cambie?Calculadora

Sin lock, cada paquete del árbol puede llegar en una versión nueva que cabe en su rango. La calculadora aplica Pigual=(1−f)k×m y Pcambia=1−Pigual. Arranca con el gateway de Alba: k = 37 paquetes, f = 10 % por paquete en un mes (un supuesto) y m = 1 mes de espera.

Que no cambie ninguno, PigualPigual=(1−f)k×m2.0 %
Que cambie al menos uno, PcambiaPcambia=1−Pigual, sin lock98.0 %
Paquetes que cambian, en promediok×(1−(1−f)m)3.7
Que cambie al menos uno, con lock y hashesse instalan los mismos archivos0.0 %
Builds sin lock, en promedio, para que uno salga idéntico al primero1÷Pigual49

Con k = 37 y f = 10 %, Pigual = 0.9³⁷ ≈ 2 %: uno de cada ≈ 49 builds. Con k = 150, como un proyecto con PyTorch, 0.9¹⁵⁰ baja a ≈ 0.00001 %, que la primera línea redondea a 0.0 %: uno de cada ≈ 7.3 millones. Aunque cada paquete cambie poco, que no cambie ninguno es casi imposible.

Prueba con 150 paquetes, una cifra común en un proyecto con PyTorch, y mira la última línea: cuántos builds sin lock harías, en promedio, para que uno saliera idéntico al primero.

El lock file: lo que instalas

Un lock file (archivo de bloqueo) es la lista exacta de todo el árbol: cada paquete, directo o transitivo, con su versión exacta y, en los buenos, el hash de cada archivo. Se genera una vez, se guarda junto al código y se instala igual en todos lados. Viene de lock, «candado»: deja las versiones bajo llave. Tiene varias formas:

  • Un requirements.txt fijado: una línea nombre==versión por paquete. El del gateway tiene las 37. Puede salir de un pip freeze de un entorno limpio, o mejor, de pip-compile (de la herramienta pip-tools) o de uv pip compile, que lo resuelven desde la lista de directas y pueden agregar los hashes.
  • uv.lock, el de uv, y poetry.lock, el de Poetry: dos gestores que leen el pyproject.toml y escriben el lock solos.
  • pylock.toml: el formato estándar que acordó el PEP 751 (2025), para que cualquier herramienta lea el lock de otra. uv lo escribe con uv export, y pip, con pip lock, que en pip 26 todavía es experimental.

¿Por qué no basta pip freeze? Porque copia lo que hay en ese entorno, en esa máquina. Si un día instalaste a mano una herramienta para probar algo, entra al lock. Si el entorno es de una Mac, la lista trae lo que necesitó la Mac, que puede no ser lo de Linux. Y no trae hashes. pip-compile y uv parten de la lista de lo que pides (un requirements.in o el pyproject.toml), resuelven desde cero y escriben solo lo necesario.

Una línea con hash se ve así (el hash, recortado):

pillow==12.3.0 \
    --hash=sha256:3f1a…

El hash es el hash criptográfico de la lección de tiempo y hashes: la huella del archivo. Si alguien cambia un solo byte de la wheel, el hash cambia. Con --require-hashes, pip se niega a instalar cualquier archivo cuyo hash no sea el del lock:

Terminal
mkdir ruedas
python - <<'PY'
import hashlib, zipfile                           # una wheel de juguete y su línea en el lock
ruta, info = "ruedas/colores-2.1.0-py3-none-any.whl", "colores-2.1.0.dist-info"
with zipfile.ZipFile(ruta, "w") as z:
    for nombre, texto in {"colores/__init__.py": "VERSION = '2.1.0'\n",
                          f"{info}/METADATA": "Metadata-Version: 2.1\nName: colores\nVersion: 2.1.0\n",
                          f"{info}/WHEEL": "Wheel-Version: 1.0\nRoot-Is-Purelib: true\nTag: py3-none-any\n",
                          f"{info}/RECORD": ""}.items():
        z.writestr(zipfile.ZipInfo(nombre, (2026, 1, 1, 0, 0, 0)), texto)
h = hashlib.sha256(open(ruta, "rb").read()).hexdigest()
open("requirements.txt", "w").write(f"colores==2.1.0 --hash=sha256:{h}\n")
PY
cut -c1-46 requirements.txt
python -m venv .venv && source .venv/bin/activate
pip install -q --no-index --find-links ruedas --require-hashes -r requirements.txt && echo "instaló: el hash coincide"
pip uninstall -q -y colores
python - <<'PY'
import zipfile                                    # alguien mete un archivo más en la wheel
with zipfile.ZipFile("ruedas/colores-2.1.0-py3-none-any.whl", "a") as z:
    z.writestr(zipfile.ZipInfo("colores/extra.py", (2026, 1, 1, 0, 0, 0)), "print('hola')\n")
PY
pip install -q --no-index --find-links ruedas --require-hashes -r requirements.txt 2>&1 | cut -c1-60
Salida
colores==2.1.0 --hash=sha256:91d3d94a49f03a53b
instaló: el hash coincide
ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUI
    colores==2.1.0 from file:///home/ana/trabajo/ruedas/colo
        Expected sha256 91d3d94a49f03a53b140a64b98b23b82e251
             Got        4ac4c9cf0b00c33413a558ed955313941000

Misma versión, mismo nombre de archivo, otro contenido: pip lo rechaza. Así se defiende producción de un archivo cambiado en el camino.

Las reglas

  • El pyproject.toml dice lo que aceptas; el lock, lo que instalas. Los dos se guardan en el repositorio del código, la carpeta del proyecto con la historia de sus versiones que vas a ver en la lección de Git.
  • Producción instala del lock, nunca de los rangos. El build de la imagen corre pip install -r requirements.txt (o uv sync --frozen, lo mismo con uv, otro gestor que verás más adelante), nunca pip install fastapi.
  • Fijado no es congelado. El mismo lock trae las mismas versiones con las mismas fallas de seguridad conocidas. Los locks se actualizan a propósito: herramientas como Dependabot o Renovate revisan seguido si hay versiones nuevas y proponen el cambio, las pruebas corren y alguien lo revisa.
06

Entornos virtuales

Esencial

Virtual environments

Un Python tiene un solo site-packages, y en él cabe una versión de cada paquete. Si un proyecto necesita NumPy 1.26 y otro NumPy 2.5, no pueden compartirlo. Y el Python del sistema operativo es del sistema: sus herramientas dependen de los paquetes que trae, y si les cambias uno, algo del sistema puede dejar de funcionar.

Una carpeta con su propio site-packages

Un entorno virtual (virtual environment, o venv) es una carpeta con su propio site-packages y un python que es un enlace al Python de base. Se crea con el módulo venv, que está en la biblioteca estándar desde Python 3.3 (2012): python -m venv .venv.

Adentro quedan tres cosas importantes:

  • .venv/bin/python: en Linux y macOS, un enlace simbólico al Python de base, como viste en «El sistema operativo». No es otra copia de Python.
  • .venv/lib/python3.13/site-packages: vacío, salvo por pip.
  • .venv/pyvenv.cfg: un archivo de texto que le dice a Python «eres un entorno virtual, tu base está en tal lugar».

Cuando Python arranca desde .venv/bin/python, lee ese archivo y pone en sys.path el site-packages del entorno en vez del de base. La biblioteca estándar sigue siendo la del Python de base.

Activar es solo cambiar el PATH

source .venv/bin/activate no hace nada mágico: pone .venv/bin al principio del PATH, para que python y pip sean los del entorno (y agrega (.venv) al prompt, para que sepas que está activo). deactivate lo regresa. Activar ni siquiera es obligatorio: correr .venv/bin/python directamente es lo mismo.

El bloque crea un entorno y lo mira por dentro: head -3 muestra las primeras tres líneas de pyvenv.cfg, readlink dice a dónde apunta el enlace python y which python dice cuál python correría la shell, antes y después de activar. Al final se sale con deactivate: En Windows la carpeta se llama Scripts en vez de bin, y se activa con .venv\Scripts\activate.

Terminal
python -m venv .venv
head -3 .venv/pyvenv.cfg
readlink .venv/bin/python
which python
source .venv/bin/activate
which python
echo "$PATH" | cut -d: -f1-2
python -m pip list
python -c "import pytest" 2>&1 | tail -1
deactivate
python -c "import pytest; print('afuera sí está pytest', pytest.__version__)"
Salida
home = /usr/local/bin
include-system-site-packages = false
version = 3.13.18
/usr/local/bin/python
/usr/local/bin/python
/home/ana/trabajo/.venv/bin/python
/home/ana/trabajo/.venv/bin:/usr/local/bin
Package Version
------- -------
pip     26.2.2
ModuleNotFoundError: No module named 'pytest'
afuera sí está pytest 8.4.2

El entorno nuevo solo tiene pip, y no ve el pytest instalado afuera: include-system-site-packages = false. Es justo lo que se quiere. Y es la historia del gateway: en la laptop, NumPy estaba instalado en el Python de siempre, y nadie lo anotó; en el entorno limpio del contenedor, no estaba.

El mismo comando, python, antes y después de activar un entorno virtual. La shell recorre las carpetas del PATH de izquierda a derecha y corre el primer python que encuentra; las demás ya no se revisan. Antes, el PATH empieza con /usr/local/bin: ahí está python, y corre /usr/local/bin/python, que ve el site-packages de base, donde está pytest. Después de source .venv/bin/activate, el PATH empieza con la carpeta nueva .venv/bin, y luego /usr/local/bin: ahora corre /home/ana/trabajo/.venv/bin/python, que ve el site-packages del entorno, con solo pip. Activar no copia ni instala nada: solo pone .venv/bin al principio del PATH, y deactivate la quita. EL PATH, DE IZQUIERDA A DERECHA Antes /usr/local/bin corre su python : /usr/bin no se revisa : … python → /usr/local/bin/python ve el site-packages de base: ahí está pytest source .venv/bin/activate Después .venv/bin, primero .venv/bin corre su python : /usr/local/bin no se revisa : … python → /home/ana/trabajo/.venv/bin/python ve el site-packages del entorno: solo pip No copia ni instala nada. deactivate la quita.
El mismo comando, python, antes y después de activar el entorno. La shell recorre el PATH de izquierda a derecha y corre el primer python que encuentra. Activar solo pone la carpeta .venv/bin al principio.

Un entorno no se mueve de lugar

Los programas que pip instala en .venv/bin, como el propio pip, son scripts cuya primera línea, el shebang, dice con qué Python correrlos, con la ruta completa de la carpeta donde se creó el entorno. Si mueves la carpeta, esa ruta ya no existe:

Terminal
python -m venv .venv
head -1 .venv/bin/pip
mv .venv otra-carpeta
./otra-carpeta/bin/pip --version
Salida
#!/home/ana/trabajo/.venv/bin/python
bash: line 4: ./otra-carpeta/bin/pip: cannot execute: required file not found

Un entorno no se copia de una máquina a otra ni se cambia de carpeta: se vuelve a crear desde el lock. Por eso el gateway lo crea en /opt/venv y lo copia a /opt/venv, la misma ruta, como vas a ver ahora.

El /opt/venv del gateway

Dentro de un contenedor solo corre una aplicación. ¿Para qué un entorno virtual? Por cómo se arma la imagen. La imagen es el paquete congelado del que nace cada contenedor, y su receta es el Dockerfile; las dos se presentan a fondo en la lección «Empaquetado con Docker». Para leer la receta basta saber cuatro palabras: FROM dice de qué imagen parte, RUN corre un comando, ENV fija una variable de entorno y COPY copia archivos adentro. La del gateway tiene dos etapas, y cada FROM empieza una. Es una ilustración, recortada:

Dockerfile
FROM python:3.13-slim AS builder
RUN python -m venv /opt/venv
ENV PATH="/opt/venv/bin:$PATH"
COPY requirements.txt .
RUN pip install --only-binary=:all: -r requirements.txt

FROM python:3.13-slim AS runtime
ENV PYTHONUNBUFFERED=1 PATH="/opt/venv/bin:$PATH"
COPY --from=builder /opt/venv /opt/venv
COPY app/ ./app/

La primera etapa crea el entorno en /opt/venv, lo «activa» con el PATH (sin activate) e instala las 37 del lock. La segunda parte de una imagen limpia y copia solo esa carpeta y el código: pip, sus caches y cualquier herramienta de la primera etapa se quedan atrás. Su PYTHONUNBUFFERED=1 es el de la lección del sistema operativo: que Python escriba cada línea de log al instante. El enlace python del entorno apunta a /usr/local/bin/python, que existe en las dos etapas porque ambas parten de python:3.13-slim.

Lo que pesa la imagen del gateway, comprimidaLa cuenta
Python y Debianla imagen base python:3.13-slim
—
≈ 43 MB
El entorno /opt/venvlas 37 dependencias; ≈ 160 MB descomprimido en disco
—
≈ 44 MB
El código, app/
—
≈ 0.048 MB
Total, la imagen de hoy S0
43 + 44 + 0.048
≈ 87 MB
Resultado
La mitad de la imagen son las dependencias, y el código del equipo es una parte en ≈ 1,800. La imagen completa python:3.13, sin slim, pesaría ≈ 0.4 GB, unas 10 veces la base slim (cifras de Docker Hub para amd64, otro nombre de x86_64, en noviembre de 2026).
De la laptop a producción: sin lock y con lock · Dos caminos de la laptop a producción. Usa «Recorrer» para ver el que truena y el que llega igual.
  • Laptop · el Python de siempre
    En el Python de siempre de la laptop, NumPy estaba instalado desde hace meses, a mano, y nadie lo anotó. Ahí el gateway arranca sin problema.
  • Build sin lock · pip install fastapi…
    El Dockerfile instala de memoria, con nombres sin versión. Falta lo que nadie anotó, y lo que sí se anotó llega en la versión de ese día, la más nueva que cabe.
  • Contenedor · truena o cambia
    O falla al arrancar con ModuleNotFoundError: No module named 'numpy', o arranca con otra Pillow que redimensiona un poco distinto, y las categorías cambian sin un solo error.
  • pyproject.toml · 9 directas, con rango
    El pyproject.toml dice lo que el equipo acepta: solo las dependencias directas, casi todas con rango, como fastapi>=0.141, y pillow==12.3.0 fija.
  • Lock con hashes · 37, con == y sha256
    El lock dice lo que se instala: todo el árbol, las 9 directas y las 28 transitivas, con versión exacta y hash. Se genera una vez, con uv pip compile o pip-compile, y se guarda en el repositorio junto al código.
  • Pruebas · un venv limpio del lock
    Las pruebas corren en un entorno virtual nuevo, instalado del mismo lock (más pytest, con requirements-dev.txt). Lo que pasa las pruebas es lo que va a correr.
  • Etapa builder · /opt/venv, solo wheels
    La primera etapa del Dockerfile crea /opt/venv e instala las 37 del lock con --only-binary=:all:. Si a un paquete le falta su wheel, el build falla aquí.
  • Gateway · slim + /opt/venv
    La segunda etapa parte de una imagen limpia y copia solo /opt/venv, a la misma ruta, y el código. Pesa ≈ 87 MB comprimida y trae las mismas 37 versiones que se probaron.
Para ir más hondo«externally-managed-environment»

Si en Debian 12, en Ubuntu reciente o con el Python de Homebrew escribes pip install requests fuera de un entorno virtual, pip se niega con el error externally-managed-environment. No es un bug: es el PEP 668. El sistema marca su Python como «manejado por otro», el gestor de paquetes del sistema operativo (la marca es un archivo llamado EXTERNALLY-MANAGED junto a su biblioteca estándar), para que pip no le cambie una librería de la que depende alguna herramienta. La salida correcta es un entorno virtual. Existe la opción --break-system-packages, y su nombre dice lo que hace. Las imágenes oficiales python:3.13 no traen esa marca: su Python vive en /usr/local, aparte del de Debian.

07

uv y conda: otros gestores

Extra

uv and conda: other managers

pip y venv vienen con Python y alcanzan para todo lo de esta lección. Pero no son los únicos, y en tutoriales y en el trabajo vas a ver otros dos muy seguido.

uv: pip, venv y el lock en uno

uv es un gestor de paquetes y proyectos de Python escrito en Rust por la empresa Astral, publicado en 2024 (en marzo de 2026, OpenAI anunció que compraría Astral; uv sigue siendo de código abierto). Hace en un solo programa lo de pip, venv, pip-tools (el lock), pipx y pyenv (las dos, al final de esta sección) y más, y es mucho más rápido: Astral dice que entre 10 y 100 veces más que pip, sobre todo cuando ya tiene los archivos en su cache. Resuelve y baja en paralelo, y guarda un cache global del que copia (o enlaza) los archivos en vez de bajarlos otra vez.

Tiene dos maneras de usarse. La primera imita a pip, para proyectos con requirements.txt:

Terminal
uv venv                                            # como python -m venv .venv
uv pip install -r requirements.txt                 # como pip install, mucho más rápido
uv pip compile requirements.in --generate-hashes -o requirements.txt   # el lock, desde las directas

La segunda maneja el proyecto completo desde el pyproject.toml:

Terminal
uv add fastapi              # lo agrega al pyproject.toml y actualiza uv.lock
uv lock                     # resuelve todo el árbol y escribe uv.lock
uv sync --frozen            # deja .venv igual al lock, sin volver a resolver
uv run pytest               # corre un comando dentro del entorno, sin activarlo

Son ilustraciones, sin salida: uv no viene con Python. El comentario del requirements.txt del gateway lo dice: en un proyecto real, ese lock se genera con uv pip compile o con pip-compile --generate-hashes.

Una diferencia importante con pip freeze: uv.lock es universal. Resuelve el árbol para todas las plataformas a la vez y anota qué wheel va en cada una. El mismo archivo sirve en la Mac del equipo y en el Linux del contenedor; un pip freeze sale de una sola máquina, con lo que esa máquina necesitó.

Poetry hace algo parecido desde hace más años, con su poetry.lock; pip-tools es la opción mínima: solo resuelve y escribe el requirements.txt fijado.

uv también instala versiones de Python: uv python install 3.13 baja un Python completo sin tocar el del sistema. Es lo que hace pyenv, otra herramienta que vas a ver en muchos tutoriales. Así, cada proyecto puede fijar no solo sus paquetes sino su intérprete, como el requires-python del pyproject.toml.

conda: cuando lo que falta no es Python

conda es otro gestor de paquetes y entornos, nacido en el mundo científico. Su diferencia de fondo: sus paquetes no son solo de Python. conda instala también compiladores, las librerías matemáticas de Intel (MKL), el toolkit de CUDA (lo que hace falta para compilar código de GPU), ffmpeg (para audio y video), librerías de mapas como GDAL, el lenguaje de estadística R… y el propio Python. Cada entorno de conda es una carpeta con todo eso adentro.

Los paquetes salen de canales: el de Anaconda, la empresa que creó conda, y conda-forge, uno comunitario y abierto con decenas de miles de paquetes. Hay versiones más rápidas del mismo programa, como mamba y micromamba.

¿Cuándo conviene?

  • Sí: cuando necesitas piezas que no son Python y pip no da, o que darían guerra compilar: una librería de mapas, un toolkit de CUDA completo para compilar, un clúster de investigación (las computadoras compartidas de un laboratorio) donde no eres root y no puedes instalar nada en el sistema.
  • Casi nunca: en la imagen de un servicio como el gateway. Las wheels ya traen su código compilado (PyTorch trae su CUDA), y la imagen slim con pip o uv es más chica y más simple.

Una trampa clásica: mezclar conda install y pip install en el mismo entorno. conda no sabe lo que pip cambió y puede pisarlo. Si no hay otra, primero todo lo de conda y pip al final. Y revisa las licencias: según los términos de servicio de Anaconda (desde 2020; el aviso en los instaladores llegó en julio de 2025), una empresa de más de 200 personas, contando contratistas, necesita una licencia de pago para usar su canal; conda-forge es libre, y Miniforge es un instalador de conda que ya viene apuntando a él.

HerramientaInstala paquetesCrea entornosEscribe un lockTrae lo que no es Python
pip + venvSí, de PyPISí, con venvNo: pip freeze es una fotoNo
pip-toolsUsa pipNoSí: requirements.txt con hashesNo
PoetrySíSíSí: poetry.lockNo
uvSí, muy rápidoSíSí: uv.lock, universalSolo el propio Python
condaSí, de sus canalesSíCon herramientas extraSí: CUDA, compiladores, R
08

Type hints y pydantic: tipos que se revisan y que no

Extra

Type hints and pydantic: types that are checked and types that are not

Type hints: anotaciones que Python no revisa

Puedes anotar qué tipo espera cada parámetro y qué tipo regresa una función. Son los type hints (type hints, «pistas de tipo»). La sintaxis existe desde Python 3.0, pero fue el PEP 484 (Python 3.5, 2015) el que acordó usarla para tipos y trajo el módulo typing:

Python
def bytes_tensor(ancho: int, alto: int) -> int:
    """Bytes de un tensor RGB en float32: 3 canales × 4 bytes."""
    return 3 * ancho * alto * 4

print(bytes_tensor(224, 224))
r = bytes_tensor("224", 1)            # el tipo está mal, y Python ni lo nota
print(r[:12], "…", type(r).__name__, "de", len(r), "letras")
print(bytes_tensor.__annotations__)
Salida
602112
224224224224 … str de 36 letras
{'ancho': <class 'int'>, 'alto': <class 'int'>, 'return': <class 'int'>}

El 602,112 son los bytes del tensor de una foto de Alba ya preparada: 3 canales × 224 × 224 píxeles × 4 bytes de cada float32. Es una foto como la de los tenis que sube Ana, una vendedora. Pero con "224", un texto, la función no se queja: 3 * "224" * 1 * 4 repite el texto 12 veces, y regresa 36 letras donde prometía un entero. Python guarda las anotaciones en __annotations__ y no las revisa al correr. Son documentación.

¿Quién las revisa? Programas aparte, antes de correr: mypy y pyright (el que va dentro de Pylance, la extensión de Python del editor VS Code) leen tu código, siguen los tipos y avisan del error sin ejecutar nada. Con mypy, la línea de arriba daría algo como esto (es una ilustración):

error: Argument 1 to "bytes_tensor" has incompatible type "str"; expected "int"

Se corren en la integración continua (CI, el proceso automático que revisa cada cambio al código; lo ves en «Pruebas y CI/CD»), junto con las pruebas: cada cambio al código pasa por ellos antes de llegar a producción. El editor también usa los tipos para autocompletar y para avisarte mientras escribes. Una línea anotada como def seed_everything(seed: int, deterministic: bool = False) -> torch.Generator: dice, sin leer el cuerpo, qué entra y qué sale.

Los tipos se combinan. Los cuatro que más vas a leer:

AnotaciónQuiere decir
list[int]Una lista de enteros
dict[str, float]Un diccionario de texto a número, como {"tenis": 0.93}
str | NoneUn texto, o nada (None): el valor puede faltar
int = 5Un entero que, si no lo pasas, vale 5

La barra | se lee «o». Un revisor como mypy te obliga a manejar el caso None antes de usar el valor como texto: atrapa justo el error de «este campo a veces no viene».

En código más viejo vas a leer lo mismo escrito de otra manera, con nombres del módulo typing: List[int] en vez de list[int] (la forma corta sirve desde Python 3.9) y Optional[str] en vez de str | None (la barra sirve desde la 3.10). Quieren decir exactamente lo mismo.

pydantic: los mismos tipos, revisados al correr

Hay datos que ningún revisor ve antes de correr: lo que llega por la red. El body de una request puede traer cualquier cosa. pydantic es una librería que usa las mismas anotaciones para revisar datos mientras el programa corre. Describes la forma de un mensaje como una clase, y pydantic revisa cada dato que la llena.

La idea cabe en unas líneas de la biblioteca estándar. Una dataclass es una clase que solo guarda campos con sus tipos; no revisa nada. Esta función de juguete lee esos tipos y convierte o rechaza cada valor, que es lo que hace pydantic, mucho más completo y rápido:

Python
from dataclasses import dataclass, fields

@dataclass
class Prediccion:
    label: str
    score: float

def validar(clase, datos):
    """Un pydantic de juguete: revisa y convierte cada campo según su tipo."""
    limpio = {}
    for campo in fields(clase):
        valor = datos[campo.name]
        try:
            limpio[campo.name] = campo.type(valor)        # str("tenis"), float("0.93")
        except (TypeError, ValueError):
            raise ValueError(f"{campo.name}: {valor!r} no es {campo.type.__name__}") from None
    return clase(**limpio)

print(validar(Prediccion, {"label": "tenis", "score": "0.93"}))
try:
    validar(Prediccion, {"label": "tenis", "score": "mucho"})
except ValueError as e:
    print("rechazado →", e)
print(Prediccion(label="tenis", score="mucho"))   # sin validar, la clase acepta lo que sea
Salida
Prediccion(label='tenis', score=0.93)
rechazado → score: 'mucho' no es float
Prediccion(label='tenis', score='mucho')

La última línea es el punto: sin alguien que revise, score queda como el texto 'mucho' y el error sale después, lejos de donde entró. El juguete tiene huecos (convertiría cualquier número en texto con str, y no sabe de rangos ni de listas); pydantic los cubre.

Así se ve el de verdad. Es una ilustración, sin salida, porque pydantic no viene con Python (pip install pydantic). Lo que imprime está en los comentarios:

Python
from pydantic import BaseModel, Field, ValidationError

class Prediccion(BaseModel):
    label: str
    score: float = Field(ge=0, le=1)          # entre 0 y 1

p = Prediccion(label="tenis", score="0.93")   # el texto "0.93" se convierte a 0.93
print(p.score, type(p.score))                 # 0.93 <class 'float'>

try:
    Prediccion(label="tenis", score=1.7)
except ValidationError as e:
    print(e.errors()[0]["msg"])               # Input should be less than or equal to 1

Fíjate en el "0.93": por omisión, pydantic convierte lo que se puede convertir sin perder nada (un texto con un número, a float) y rechaza lo demás. Si quieres que no convierta nada, tiene un modo estricto (strict=True). Desde su versión 2 (2023), el corazón de pydantic es pydantic_core, escrito en Rust: una de las extensiones nativas del gateway.

Ese cambio de MAYOR también rompió cosas, como promete el semver. La versión 2 renombró los métodos de siempre: .dict() pasó a ser .model_dump(), .json() pasó a .model_dump_json() y parse_obj() pasó a model_validate(). Los nombres viejos siguen ahí, con un aviso de que se van a quitar, así que un tutorial de antes de 2023 casi corre, pero no del todo. Fíjate en qué versión de pydantic supone un ejemplo antes de copiarlo.

Su uso más famoso es FastAPI, el framework (un armazón de código listo para escribir servidores) con que está escrito el gateway de Alba, que tiene su lección en «Código de serving». FastAPI lee los tipos de cada parámetro y del body, valida cada request con pydantic y, si algo no cumple, responde 422 sin llegar a tu función, como viste en la lección de APIs. En la lección de configuración vas a ver pydantic-settings, que hace lo mismo con las variables de entorno: INFER_TIMEOUT_S=0.15 llega como texto y sale como un número revisado.

09

Errores comunes

Esencial

Common mistakes

1. Instalar con el pip de otro Python

pip install pillow dice «Successfully installed», y import PIL falla. El pip que corriste era de otro Python, o de otro entorno.

Cómo evitarlo: usa python -m pip, y ante la duda, which python, python -m pip --version y python -c "import sys; print(sys.prefix)" (la carpeta del Python o del entorno que corre): los tres deben hablar del mismo lugar.

2. pip install sin versiones

Un notebook (un cuaderno de Jupyter, donde se mezclan código y texto) con pip install torch fastapi pillow funciona hoy. En tres meses, el mismo notebook instala otras versiones, y el modelo que entrenaste ya no se puede reproducir. En un Dockerfile es un error clásico, y también una trampa de seguridad: sin versión, recibes lo último que se publicó, aunque venga con código malicioso.

Cómo evitarlo: las directas en el pyproject.toml, todo el árbol en un lock con hashes, y producción instalando solo del lock.

3. Un archivo con el nombre de un módulo

Tu json.py, random.py o torch.py tapa al de verdad, y el error que sale (AttributeError: module 'json' has no attribute 'dumps') no menciona tu archivo.

Cómo evitarlo: nombres propios para tus archivos (mi_json.py, preprocess.py), y ante algo raro, print(modulo.__file__). El .pyc viejo que queda en __pycache__ al renombrarlo no estorba: Python ignora un .pyc de esa carpeta cuyo .py ya no existe.

4. Una wheel de otra plataforma

En la Mac, todo instala en segundos. En el contenedor, pip intenta compilar un paquete y falla por falta de gcc; o en una imagen Alpine, PyTorch ni siquiera tiene wheel.

Cómo evitarlo: imágenes slim con glibc, no Alpine, para ML; --only-binary=:all: para que una wheel que falta se note al construir; y un lock que conozca la plataforma de producción (uno universal, o uno generado en Linux).

5. Instalar fuera del entorno

sudo pip install en el Python del sistema, o --break-system-packages para callar el error del PEP 668. Funciona hasta que una herramienta del sistema se rompe, o hasta que nadie sabe qué hay instalado.

Cómo evitarlo: un entorno virtual por proyecto, siempre. Es una carpeta: si se ensucia, se borra y se vuelve a crear desde el lock en segundos.

6. PyTorch con CUDA donde no hay GPU

Un servicio que corre en CPU instala torch desde PyPI «por si acaso» y la imagen sube de ≈ 0.09 GB a más de 3. O al revés: la imagen trae un CUDA más nuevo que el que acepta el driver del nodo (la máquina del clúster donde corre), y el modelo corre en CPU casi sin avisar.

Cómo evitarlo: el índice /whl/cpu donde no hay GPU, y donde sí, revisar la versión de CUDA de la wheel contra el driver (torch.version.cuda, y torch.cuda.is_available() al arrancar, con un error si da False).

10

En la vida real

Extra

In real life

Alba: la imagen del gateway y la Pillow que no se mueve

El gateway de Alba es el ejemplo de esta lección completa. Su requirements.txt fija las 37 dependencias con ==, transitivas incluidas, y un comentario dice por qué: sin lock, reconstruir el mismo commit puede traer otra Starlette u otro NumPy y cambiar el comportamiento sin que nadie toque el código. La imagen se arma en dos etapas con /opt/venv, solo con wheels, y pesa ≈ 87 MB comprimida.

La dependencia más vigilada es Pillow. El gateway decodifica y redimensiona cada foto con Pillow, y el entrenamiento también. Si las dos versiones difieren, el resize puede dar píxeles un poco distintos y el modelo recibe fotos que no son como las que vio al entrenar. Por eso pillow==12.3.0 aparece igual en el entorno del gateway y en el del job que exporta el modelo, y el preprocesamiento es un solo módulo, app/preprocess.py, que importan el entrenamiento, la evaluación y el gateway.

Las pruebas usan las mismas versiones que producción: el requirements-dev.txt empieza con -r requirements.txt (incluye el lock de producción) y solo agrega pytest y un cliente HTTP con sus transitivas. Y el job de exportación fija torch==2.14.0 a propósito: el exportador de modelos (la parte de torch que guarda el modelo entrenado como un archivo ONNX, un formato para modelos) cambia entre versiones.

Lo que pesa la imagen, y lo que tarda en bajarCalculadora

Arranca con la imagen del gateway de Alba, comprimida: la base python:3.13-slim (≈ 43 MB), el entorno /opt/venv con las 37 dependencias (≈ 44 MB) y el código, Scódigo ≈ 0.048 MB; juntos son la imagen de hoy, S0 ≈ 87 MB. La calculadora aplica S=Sbase+Svenv+Storch+Scódigo y t=S÷v. Pon 1 para agregar torch solo para CPU (≈ 196 MB) o 2 para torch con CUDA y sus librerías (≈ 3,000 MB).

torch y sus librerías, Storch, en MB0 si no lo agregas; 196 con 1; 3,000 con 20
Imagen completa, comprimida, SS=Sbase+Svenv+Storch+Scódigo, con Scódigo = 0.048 MB87.0 MB
Veces la imagen actual del gateway (≈ 87 MB)S÷S0, con S0 = 87.048 MB1.0×
Segundos para bajarla en un nodo nuevo, tt=S÷v, antes de arrancar siquiera0.9
Lo que viaja por la red con todos los nodosS×\nodos870 MB
Parte de la imagen que son dependencias(Svenv+Storch)÷S50.5 %

Con 2, la imagen pasa de ≈ 87 MB a ≈ 3,087 MB (3.09 GB), unas 35.5 veces más, y cada nodo tarda ≈ 31 s en bajarla a 100 MB/s. Con 1, ≈ 283 MB. El código del equipo casi no pesa: lo que pesa son las dependencias.

Arranca con la imagen del gateway. Prueba agregar torch solo para CPU (1) y con CUDA (2), y mira cuánto tarda cada nodo en bajarla.

Por qué el gateway no importa torch

Fíjate en lo que no está entre las 37: PyTorch. El gateway prepara el tensor y se lo manda a Triton, el servidor de modelos de NVIDIA, que corre el modelo en la GPU. Esa separación también es una decisión de paquetes. La imagen nueva pesa lo de hoy más torch, S=S0+Storch, y un nodo tarda en bajarla t=S÷v, con v la velocidad de su red en MB/s:

Si el gateway importara torch con CUDALa cuenta
Imagen actual, S0base, entorno y código
43 + 44 + 0.048
≈ 87 MB
torch con CUDA y sus librerías, Storchtorch 2.14 de PyPI con CUDA, de la sección «PyTorch: el paquete que pesa gigas»
—
≈ 3,000 MB
Imagen con torch, S
S=S0+Storch = 87 + 3,000
≈ 3,087 MB
Veces más grande
S÷S0 = 3,087 ÷ 87
≈ 35.5
Velocidad de la red del nodo, vun supuesto de red
—
100 MB/s
Bajarla en un nodo nuevo, t
t=S÷v = 3,087 ÷ 100
≈ 31 s
Resultado
Con torch, cada réplica nueva tardaría ≈ 31 s solo en bajar la imagen, contra menos de 1 s hoy (87 ÷ 100 ≈ 0.9 s). El peso de PyTorch y CUDA lo carga una sola imagen, la de Triton: ≈ 9.2 GB comprimida, la release 24.08 de NGC (el catálogo de imágenes de NVIDIA) para x86_64.

Esa espera es parte del arranque en frío (cold start): el tiempo que pasa desde que se pide una réplica nueva hasta que responde. Cuando llega un pico y el sistema agrega réplicas, cada una empieza por bajar su imagen. Un gateway liviano escala en segundos.

LiteLLM: un día sin lock

Un caso real de 2026: las versiones 1.82.7 y 1.82.8 de LiteLLM, una librería muy usada para hablar con LLMs, salieron comprometidas en PyPI el 24 de marzo. Quien corrió pip install litellm sin versión en las pocas horas que estuvieron publicadas recibió el código malicioso. La 1.82.8 traía además un archivo .pth en site-packages, de los que Python lee cada vez que arranca: el código corría aunque nadie importara litellm. Quien instalaba de un lock con hashes, hecho antes, no recibió nada: pip habría rechazado cualquier archivo distinto al revisado. Por eso la defensa de la cadena de suministro pide índices revisados y versiones fijadas con hash; la ves en «Ataques y cadena de suministro».

En los sistemas con LLMs el problema se agranda. Pasa en un servicio que sirve su propio LLM y en el asistente interno de Alba, que responde las preguntas de sus ≈ 8,000 empleados con los documentos de la empresa: la pila cambia cada mes, las imágenes con vLLM y CUDA pesan varios GB, y el consejo es el mismo: fija versiones.

En el edge: otro chip, otras wheels

Piensa en un sistema de video en tiempo real con varias cámaras, repartido en varios centros de distribución: cada centro tiene su propia caja con una GPU que vigila las cámaras. Si una caja así fuera un equipo ARM, como los Jetson de NVIDIA, el mismo requirements.txt del servidor no serviría: pip buscaría wheels aarch64 y, para PyTorch con CUDA en esos equipos, NVIDIA publica sus propias wheels, atadas a la versión de su sistema (JetPack). El lock del edge es otro lock, armado y probado en esa plataforma. Es la sección de wheels llevada al extremo: el nombre del archivo decide dónde corre.

Reproducir un modelo meses después

Reproducir un entrenamiento pide varios ingredientes: el mismo código, los mismos datos, la misma semilla y el mismo entorno. El entorno es la imagen identificada por su huella (su digest) y las dependencias fijadas; lo ves en «Versionado y linaje». Un ejemplo de por qué importa: un valor por omisión cambió entre dos versiones de una librería, y el mismo código entrenó otra cosa.

Fuera de ML: once líneas que rompieron internet

En marzo de 2016, un programador quitó de npm, el índice de paquetes de JavaScript, un paquete de once líneas llamado left-pad, que rellenaba un texto con espacios a la izquierda. Miles de proyectos dependían de él sin saberlo, como dependencia transitiva de herramientas famosas, y sus builds empezaron a fallar en todo el mundo. npm terminó cambiando sus reglas para que un paquete usado por otros no se pudiera borrar así.

Cada lenguaje resolvió lo mismo con su propio lock: package-lock.json en JavaScript, Cargo.lock en Rust, Gemfile.lock en Ruby, go.mod con go.sum en Go. La idea es la de esta lección: lo que pides cabe en un rango; lo que instalas tiene que ser exacto.

11

Ejercicios

Esencial

Exercises

Resuélvelos antes de abrir la solución. Los de tamaños y probabilidades se pueden comprobar con las calculadoras.

  1. 1Fácil

    Tu carpeta tiene app.py y un random.py tuyo con una sola función. app.py hace import random y llama random.randint(1, 6). ¿Qué pasa con python app.py? ¿Y con python -I app.py?

    Ver la solución paso a paso
    • Con python app.py, la carpeta del script va primero en sys.path: import random carga tu random.py. Como no tiene randint, sale AttributeError: module 'random' has no attribute 'randint'.
    • Con python -I app.py, la carpeta del script no entra a sys.path: se carga el random de la biblioteca estándar y funciona.
    • El arreglo de verdad no es -I, es renombrar tu archivo.
  2. 2Fácil

    El gateway corre en Linux x86_64 con Python 3.13. ¿Cuáles de estas wheels puede usar (nombres simplificados)? pillow-12.3.0-cp313-cp313-macosx_11_0_arm64.whl, pillow-12.3.0-cp313-cp313-manylinux_2_28_x86_64.whl y starlette-1.7.0-py3-none-any.whl.

    Ver la solución paso a paso
    • La de macOS, no: es para una Mac con chip de Apple.
    • La manylinux_2_28_x86_64, sí: Linux con glibc 2.28 o más nueva en x86_64, compilada para CPython 3.13 (cp313). Debian, la base de python:3.13-slim, tiene glibc.
    • La de Starlette, sí: py3-none-any es puro Python y sirve en cualquier lado.
  3. 3Fácil

    Alguien escribe pip install PIL y, después de instalar bien, import pillow. Los dos fallan. ¿Por qué, y qué se escribe?

    Ver la solución paso a paso
    • El nombre que se instala no es el que se importa. En PyPI el paquete se llama pillow; adentro trae el paquete de import PIL.
    • Se escribe python -m pip install pillow y, en el código, from PIL import Image.
  4. 4Fácil

    ¿Qué versiones de esta lista acepta numpy~=2.5.0: 2.4.9, 2.5.0, 2.5.7, 2.6.0 y 3.0.0? ¿Y numpy>=2.5?

    Ver la solución paso a paso
    • ~=2.5.0 quiere decir «2.5.0 o más nueva, sin salir de la 2.5»: acepta 2.5.0 y 2.5.7.
    • >=2.5 acepta 2.5.0, 2.5.7, 2.6.0 y 3.0.0. La 3.0.0 es una MAYOR: puede romper. Por eso los rangos sin tope son una apuesta.
  5. 5Medio

    El entorno de pruebas del gateway instala requirements-dev.txt: todo el requirements.txt (37 paquetes) más pytest y un cliente HTTP, que traen 6 transitivas. ¿Cuántos paquetes tiene el entorno de pruebas? ¿Cuántos de ellos no llegan a la imagen de producción?

    Ver la solución paso a paso
    • Entorno de pruebas: 37 + 2 + 6 = 45 paquetes.
    • No llegan a producción: 2 + 6 = 8. La imagen se construye solo con requirements.txt.
    • Lo importante es lo que sí comparten: las 37 de producción, con las mismas versiones. Así, lo que pasó las pruebas es lo que corre.
  6. 6Medio

    En una laptop corres source .venv/bin/activate y luego /usr/bin/python3 -m pip install requests. ¿Dónde se instala requests? ¿Lo ve python -c "import requests"?

    Ver la solución paso a paso
    • Activar solo cambió el PATH. Pero escribiste la ruta completa /usr/bin/python3: la shell no busca en el PATH, corre ese Python, el del sistema. Su pip instala fuera del entorno: en el Python del sistema, o en tu carpeta de usuario si el del sistema no se deja escribir. Eso, si el PEP 668 lo deja: en Debian, Ubuntu o Homebrew, se niega.
    • python, con el entorno activado, es .venv/bin/python: ve solo el site-packages del entorno. No ve requests: ModuleNotFoundError.
    • Con python -m pip install requests, sin ruta, se habría instalado en el entorno.
  7. 7Medio

    Un servicio en CPU tiene una imagen de ≈ 87 MB. Alguien agrega torch desde PyPI, con CUDA (≈ 3,000 MB), para una función auxiliar. ¿Cuánto pesa la imagen ahora? Si 10 nodos nuevos la bajan, ¿cuántos GB viajan por la red? ¿Y si usara la wheel de CPU (≈ 196 MB)?

    Ver la solución paso a paso
    • La imagen nueva es S=S0+Storch, y lo que viaja es S×\nodos.
    • Con CUDA: S = 87 + 3,000 ≈ 3,087 MB, ≈ 35.5 veces más (3,087 ÷ 87). Diez nodos: 10 × 3.087 GB ≈ 30.9 GB.
    • Con la wheel de CPU: S = 87 + 196 ≈ 283 MB; diez nodos, 10 × 0.283 GB ≈ 2.8 GB.
    • Y la pregunta de fondo: si la función auxiliar no necesita la GPU, quizá tampoco necesita torch.
  8. 8Medio

    Con la calculadora del rebuild: un proyecto tiene 37 paquetes, y cada uno saca en un mes una versión nueva dentro de su rango con probabilidad de 5 % (un supuesto). ¿Qué tan probable es que reconstruir sin lock, un mes después, instale algo distinto? ¿Y con un lock con hashes?

    Ver la solución paso a paso
    • Se usa Pigual=(1−f)k×m con k = 37, f = 0.05 y m = 1.
    • Que no cambie ninguno: Pigual = 0.95³⁷ ≈ 0.15. Que cambie al menos uno: Pcambia=1−Pigual = 1 − 0.15 ≈ 85 %.
    • Con lock y hashes: 0 %. Se instalan los mismos archivos; si uno cambiara, pip lo rechazaría.
    • Aun con un supuesto bajo, sin lock lo normal es que algo cambie.
  9. 9Reto

    El gateway funciona en la Mac de quien lo escribió. En el contenedor arranca con un error que empieza así: «A module that was compiled using NumPy 1.x cannot be run in NumPy 2.5.3». ¿Qué pasó, y en qué orden lo revisas?

    Ver la solución paso a paso
    • El mensaje dice que una extensión nativa se compiló contra NumPy 1.x y ahora encontró NumPy 2: la MAYOR que cambió la interfaz binaria. Alguna dependencia trae una wheel vieja, o pide un rango que dejó entrar a NumPy 2.
    • Primero, qué hay instalado de verdad: python -m pip freeze dentro del contenedor, y importlib.metadata.requires() del sospechoso, para ver qué rango de NumPy pide.
    • Segundo, comparar con la laptop: si allá hay NumPy 1.26, el entorno de la laptop no salió del lock (alguien instaló a mano).
    • El arreglo: elegir la combinación que funciona (subir el paquete que se compiló contra 1.x, o fijar numpy<2 si aún no hay versión nueva), regenerar el lock, correr las pruebas y construir la imagen desde el lock. Nunca «arreglarlo» con un pip install dentro del contenedor que está corriendo.
  10. 10Reto

    El job de entrenamiento de Alba necesita torch con CUDA; el gateway, no. Los dos usan el mismo preprocesamiento con Pillow. ¿Cómo organizas sus dependencias, sus locks y sus imágenes para que el resize sea idéntico y cada imagen pese lo justo?

    Ver la solución paso a paso
    • Dos entornos, dos locks, dos imágenes. El del entrenamiento lleva torch con CUDA (gigas); el del gateway, solo lo que importa app/ (≈ 87 MB).
    • Lo compartido, fijado igual en los dos: pillow==12.3.0 y NumPy con la misma versión, y el preprocesamiento como un solo módulo que los dos importan.
    • Una prueba que lo vigile: una prueba de paridad del preprocesamiento: las mismas fotos, por los dos entornos, deben dar tensores iguales dentro de una tolerancia. Si alguien sube Pillow en un lock y no en el otro, la prueba falla antes de llegar a producción.
    • Cada lock se actualiza a propósito, con su propia revisión.
12

Lo que sigue

Esencial

What comes next

La siguiente lección, «PyTorch en lo que toca a producción», instala torch y lo usa de verdad. Después vienen «Git: versiones del código», donde se guardan el pyproject.toml y el lock; «Pruebas y CI/CD», donde pytest corre sobre el entorno instalado del lock; y «Configuración: YAML, variables de entorno y secretos», con pydantic-settings. Ya en el sistema de Alba, «Empaquetado con Docker» construye la imagen del gateway con este mismo /opt/venv y mira lo que pesa cada capa.

13

Palabras que vas a oír

Esencial

Words you will hear

Estos son los conceptos que presentó esta lección. Cada uno tiene su tarjeta con la definición completa.

Módulo de PythonmoduleUn archivo .py que otro código usa con import. Su nombre es el del archivo sin la extensión: preprocess.py es el módulo preprocess.Más

Al hacer import json, Python busca el módulo en las carpetas de sys.path, en orden, y gana el primero que aparece: la carpeta del script, las de PYTHONPATH, la biblioteca estándar y site-packages. Lo corre una sola vez, de arriba abajo, y lo guarda en sys.modules: si otro archivo lo vuelve a importar, recibe el mismo objeto. Si no lo encuentra, truena con ModuleNotFoundError. Como la carpeta del script va primero, un json.py tuyo tapa al de verdad; python -I la deja fuera. Cada módulo sabe su nombre en __name__, que vale "__main__" cuando es el programa que arrancó. python -m nombre busca un módulo igual que import y lo corre como programa. Un módulo también puede ser código compilado, un .so: una extensión nativa.

Ejemplo. En el gateway de Alba, app/preprocess.py es el módulo app.preprocess, el que decodifica y redimensiona la foto; uvicorn app.main:app quiere decir «del módulo app.main, el objeto app».

Ver en el glosario →

Paquete de PythonpackageUna carpeta de módulos, normalmente con un archivo __init__.py adentro. Los puntos de un import son carpetas: app.preprocess es el archivo preprocess.py dentro de la carpeta app.Más

La palabra se usa para dos cosas. El paquete que se importa es la carpeta de módulos. Lo que se instala de PyPI también se llama paquete (más exacto: distribución), y su nombre no siempre es el que se importa: se instala pillow y se importa PIL; se instala scikit-learn y se importa sklearn; se instala PyYAML y se importa yaml. Por eso pip install PIL no sirve y import pillow da ModuleNotFoundError. Lo que va entre corchetes, como tritonclient[http], es un extra: una parte opcional con sus propias dependencias.

Ejemplo. El gateway de Alba es un paquete: la carpeta app/ con __init__.py, main.py (crea el servidor) y preprocess.py. Por eso se puede escribir from app.preprocess import preprocess.

Ver en el glosario →

Biblioteca estándarstandard libraryLos ≈ 200 módulos que llegan con cualquier instalación de Python, sin instalar nada: json, math, hashlib, sqlite3, asyncio y muchos más. Por eso se dice que Python viene «con pilas incluidas».Más

Python 3.13 enumera 192 nombres públicos, sin contar los internos que empiezan con guion bajo. Vive en una carpeta del Python de base, como /usr/local/lib/python3.13, con su subcarpeta lib-dynload de piezas compiladas (math es un .so), y algunos módulos, como sys, vienen dentro del intérprete mismo (built-in). En sys.path va después de la carpeta del script y antes de site-packages. Todo lo demás (NumPy, Pillow, FastAPI, PyTorch) son paquetes de terceros que se instalan con pip: no los escribió el equipo de Python y cada uno tiene su propio ritmo de versiones. Un entorno virtual no copia la biblioteca estándar: usa la del Python de base.

Ejemplo. python -m json.tool datos.json imprime un JSON con sangría, fácil de leer usando solo la biblioteca estándar; tomllib, desde la 3.11, lee un pyproject.toml.

Ver en el glosario →

pippipEl instalador de paquetes que viene con Python: baja paquetes del índice público PyPI (o de otro índice) y los copia en la carpeta de paquetes instalados (site-packages), junto con todo lo que ellos piden.Más

Sus comandos de todos los días: pip install pillow==12.3.0, pip install -r requirements.txt, pip list, pip freeze (lo instalado como nombre==versión), pip show y pip uninstall. Por dentro tiene un resolvedor (resolver) que busca una versión de cada paquete que cumpla todas las reglas; si dos chocan, como colores>=2.0 y colores<2, se rinde con ResolutionImpossible. En una máquina puede haber varios Pythons, y el comando pip es el primero que la shell encuentra en el PATH: puede ser de otro Python. Por eso se usa python -m pip, que corre el pip de ese Python. Con --require-hashes revisa el hash de cada archivo contra el lock; con --only-binary=:all: se niega a compilar.

Ejemplo. Si pip install pillow dice «Successfully installed» y import PIL falla, which python, python -m pip --version y python -c "import sys; print(sys.prefix)" deben hablar del mismo lugar. En un contenedor de prueba: pip 26.2.2 from /usr/local/lib/python3.13/site-packages/pip (python 3.13).

Ver en el glosario →

PyPIPython Package IndexEl índice público de paquetes de Python, en pypi.org: un servidor con cientos de miles de proyectos (≈ 940,000 a mediados de noviembre de 2026), cada uno con todas sus versiones y sus archivos. Es de donde pip baja por omisión.Más

Cualquiera puede crear una cuenta y subir un paquete. Eso lo hace enorme y también riesgoso: el typosquatting son paquetes con nombres casi iguales a los famosos, esperando un error de dedo, y la confusión de dependencias (dependency confusion) es publicar en PyPI un paquete con el nombre de uno interno de una empresa y una versión más alta, para que --extra-index-url lo prefiera. Por eso las empresas suelen tener un espejo (mirror) propio, con copias revisadas, que pip usa con --index-url. Es parte de la cadena de suministro.

Ejemplo. Un caso real: las versiones 1.82.7 y 1.82.8 de LiteLLM salieron comprometidas en PyPI el 24 de marzo de 2026: quien corrió pip install litellm sin versión en las pocas horas que estuvieron publicadas recibió el código malicioso, y quien instalaba de un lock con hashes, no.

Ver en el glosario →

WheelwheelEl archivo .whl en que se reparte un paquete de Python ya armado: un zip que se copia tal cual a la carpeta de paquetes instalados (site-packages), sin necesitar un compilador. Su nombre dice para qué Python, sistema y chip sirve.Más

Adentro trae los archivos del paquete y una carpeta .dist-info con su ficha: nombre, versión, lo que pide (Requires-Dist) y, en RECORD, el hash de cada archivo. Instalarla es, en lo esencial, descomprimirla: no hace falta ningún compilador. La otra forma de repartir un paquete es el sdist (source distribution), el código fuente en un .tar.gz, que pip tiene que construir, a veces con un compilador. El nombre tiene cinco partes: nombre, versión y una etiqueta de tres, con qué Python se compiló, con qué interfaz binaria (ABI) y para qué sistema y chip. py3-none-any es puro Python y sirve en cualquier lado; manylinux_2_28_x86_64 es Linux con glibc 2.28 o más nueva en x86_64; musllinux es para Alpine, y muchos paquetes de ML no la publican. pip escoge la más específica que sirva en tu máquina.

Analogía. Un mueble ya armado contra uno en caja para armar: el armado entra directo, pero solo por puertas de su medida. Se rompe en que, si no hay mueble armado de tu medida, pip no se rinde: baja la caja (el sdist) y lo arma él, si tiene las herramientas (un compilador).

Ejemplo. numpy-2.5.3-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl (un nombre con dos etiquetas de Linux a la vez) sirve en el contenedor del gateway (Linux x86_64 con glibc, Python 3.13); numpy-2.5.3-cp313-cp313-macosx_14_0_arm64.whl es la de una MacBook, y fastapi-0.141.1-py3-none-any.whl sirve en las dos.

Ver en el glosario →

Extensión nativanative extensionUn módulo de Python escrito en C, C++, Rust o CUDA (para programar GPUs de NVIDIA) y ya compilado a instrucciones de una CPU: un archivo .so en Linux y macOS o .pyd en Windows. Se importa como cualquier módulo, pero adentro no hay Python.Más

Existen por velocidad: Python puro hace las cuentas de una en una, y NumPy, Pillow y PyTorch hacen el trabajo pesado en C y C++, y pueden soltar el GIL mientras tanto. Pillow trae además librerías de imágenes compiladas, como las de JPEG; pydantic_core está escrito en Rust; PyTorch trae C++ y kernels de CUDA. El precio: como el código está compilado para un sistema, un chip y una versión de Python, el paquete necesita una wheel por plataforma, y el mismo numpy==2.5.3 son archivos distintos en una Mac y en el contenedor. También quedan atadas a la interfaz binaria (ABI: las reglas de cómo el código compilado se conecta con lo que llama) de lo que usan: las extensiones compiladas contra NumPy 1.x dejaron de cargar con NumPy 2.

Ejemplo. En un contenedor de prueba, math es /usr/local/lib/python3.13/lib-dynload/math.cpython-313-aarch64-linux-gnu.so: el aarch64 dice que es para un chip ARM. De las 37 dependencias del gateway, 17 traen código compilado en su wheel de Linux, como numpy, pillow, pydantic_core y uvloop.

Ver en el glosario →

DependenciadependencyUn paquete que tu código necesita para correr. Si tu servidor importa FastAPI, FastAPI es su dependencia.Más

Las que tú pides por su nombre son las directas, y van en el pyproject.toml con un rango de versiones que aceptas. Pero cada una pide otras, las transitivas, y todas juntas forman un árbol. En un site-packages cabe una versión de cada paquete: si una dependencia pide colores>=2.0 y otra colores<2, hay un conflicto de dependencias y pip se rinde. Algunas llevan una condición (marker) después de un ;, como colorama>=0.4; sys_platform == "win32": pytest la pide solo en Windows, así que el árbol cambia según la plataforma. La biblioteca estándar lee las de cada paquete con importlib.metadata.requires().

Ejemplo. El gateway de Alba pide 9 directas: fastapi, uvicorn, uvloop, httptools, pillow, numpy, tritonclient, aiohttp y prometheus-client.

Ver en el glosario →

Dependencia transitivatransitive dependencyUn paquete que llega porque lo pide algo que tú pediste, en cualquier nivel del árbol. Nadie lo pidió por su nombre, pero igual corre en producción.Más

FastAPI necesita Starlette (la parte que habla HTTP) y Pydantic (la que valida datos), y Pydantic necesita pydantic_core: Starlette, Pydantic y pydantic_core son transitivas del gateway. Un mismo paquete puede colgar de dos ramas, como idna, que piden anyio y yarl, pero se instala una sola vez. Como pueden cambiar de versión sin que nadie las toque, se fijan todas en el lock file, no solo las directas.

Analogía. Invitas a cuatro amigos y cada uno trae a sus amigos: en la fiesta hay gente que no conoces, y también rompe cosas. Se rompe en que aquí sí puedes saber quién llegó: el lock file trae la lista completa de invitados.

Ejemplo. El gateway pide 9 y le llegan 37: 28 son transitivas, ≈ 3.1 por cada directa. Tres de cada cuatro paquetes del gateway (28 de 37, ≈ 76 %) nadie los pidió por su nombre.

Ver en el glosario →

Versionado semánticosemantic versioning · semverLa costumbre de numerar las versiones como MAYOR.MENOR.PARCHE, como 2.5.3: subir el PARCHE solo arregla errores, subir la MENOR agrega cosas sin romper y subir la MAYOR puede romper.Más

Es una promesa, no una regla que alguien revise. Las 0.x no prometen nada: FastAPI lleva años en 0.x, y el gateway usa la 0.141. No todos lo usan: pip (26.2), certifi (2026.7.22) y attrs (26.1.0) numeran por fecha. Una MAYOR rompe de verdad: NumPy 2.0 (2024) cambió su interfaz binaria y las extensiones compiladas contra NumPy 1.x dejaron de cargar. Y un arreglo también puede cambiar resultados: otra Pillow puede redimensionar un poco distinto, y el accuracy baja sin un solo error, un training-serving skew. Los rangos se escriben con las reglas del PEP 440: ==2.5.3 (exacta), >=2.5 (esa o más nueva, incluida la 3.0), >=2,<3 (con tope) y ~=2.5.3 («compatible»: 2.5.3 o más nueva sin salir de la 2.5).

Ejemplo. De la lista 1.26.4, 2.0.0, 2.5.2, 2.5.3, 2.5.4, 2.6.0 y 3.0.0, ~=2.5.3 acepta 2.5.3 y 2.5.4; >=2.5 acepta también la 3.0.0, la que puede romper.

Ver en el glosario →

Lock filelock fileLa lista exacta de todo lo que se instala: cada paquete del árbol, directo o transitivo, con su versión exacta y, en los buenos, el hash (la huella) de cada archivo. Se genera una vez, se guarda junto al código y se instala igual en todos lados.Más

Tiene varias formas: un requirements.txt fijado, con una línea nombre==versión por paquete (mejor si sale de pip-compile o de uv pip compile, que resuelven desde las directas y agregan hashes), uv.lock, poetry.lock o pylock.toml, el formato estándar del PEP 751 (2025). Un pip freeze no basta: copia lo que hay en ese entorno, en esa máquina, con lo que alguien instaló a mano y sin hashes. Con pip install --require-hashes, pip se niega a instalar un archivo cuyo hash no sea el del lock. Las reglas: el pyproject.toml dice lo que aceptas y el lock lo que instalas; producción instala del lock, nunca de los rangos; y fijado no es congelado: el lock se actualiza a propósito, con herramientas como Dependabot o Renovate, pruebas y revisión.

Analogía. La receta dice «harina»; el ticket del súper dice la marca, el lote y el precio. Con el ticket compras exactamente lo mismo. Se rompe en que el ticket no obliga al súper a seguir vendiendo ese lote: si el índice borra una versión, el lock ya no se puede instalar tal cual.

Ejemplo. El requirements.txt del gateway de Alba fija las 37 dependencias con ==. Sin lock, con 37 paquetes y 10 % de que cada uno cambie en un mes (un supuesto), reconstruir el mismo commit un mes después instala algo distinto con probabilidad 1 − 0.9³⁷ ≈ 98 % (1 menos la probabilidad de que no cambie ninguno: 0.9 multiplicado por sí mismo 37 veces); con lock y hashes, 0 %.

Ver en el glosario →

Entorno virtualvirtual environment · venvUna carpeta con su propia carpeta de paquetes instalados (site-packages) y un python que es un enlace al Python de base. Cada proyecto instala ahí sus paquetes sin tocar los de otros ni los del sistema.Más

Se crea con python -m venv .venv; el módulo venv está en la biblioteca estándar desde Python 3.3. Adentro quedan .venv/bin/python (en Linux y macOS, un enlace simbólico, no otra copia de Python), .venv/lib/python3.13/site-packages (vacío salvo por pip) y .venv/pyvenv.cfg, que le dice a Python dónde está su base. La biblioteca estándar sigue siendo la del Python de base, y con include-system-site-packages = false el entorno no ve lo instalado afuera. source .venv/bin/activate solo pone .venv/bin al principio del PATH; deactivate lo quita, y correr .venv/bin/python directo es lo mismo. Un entorno no se mueve de carpeta: los scripts de .venv/bin llevan en su shebang la ruta completa donde se creó. Se vuelve a crear desde el lock.

Analogía. Una mochila por proyecto: cada una con sus útiles, y el estante del salón (el Python del sistema) no se toca. Se rompe en que la mochila no trae su propio Python ni su biblioteca estándar: usa los del Python de base, y si ese se borra, el entorno deja de servir.

Ejemplo. La imagen del gateway de Alba crea el entorno en /opt/venv en la etapa builder, instala ahí las 37 del lock y la etapa final copia solo esa carpeta, a la misma ruta, con PATH="/opt/venv/bin:$PATH".

Ver en el glosario →

condacondaUn gestor de paquetes y entornos nacido en el mundo científico cuyos paquetes no son solo de Python: también instala compiladores, librerías de C, el toolkit de CUDA (para programar GPUs de NVIDIA), el lenguaje R y el propio Python.Más

Cada entorno de conda es una carpeta con todo eso adentro. Los paquetes salen de canales: el de Anaconda, la empresa que lo creó, que desde 2020 pide licencia de pago a las organizaciones de más de 200 personas, contando contratistas (sus términos vigentes son de julio de 2025), y conda-forge, comunitario y libre. mamba y micromamba son versiones más rápidas del mismo programa. Conviene cuando necesitas piezas que no son Python y pip no da, o en un clúster donde no eres root; casi nunca en la imagen de un servicio, porque las wheels ya traen su código compilado y la imagen slim con pip o uv es más chica. Una trampa clásica: mezclar conda install y pip install en el mismo entorno, porque conda no sabe lo que pip cambió.

Ejemplo. El gateway de Alba no usa conda: su imagen es python:3.13-slim con un entorno de pip en /opt/venv, ≈ 87 MB comprimida.

Ver en el glosario →

uvuvUn gestor de paquetes y proyectos de Python escrito en Rust por la empresa Astral, publicado en 2024: un solo programa instala paquetes (como pip), crea entornos virtuales (como venv) y escribe lock files (como pip-tools); Astral dice que entre 10 y 100 veces más rápido que pip.Más

Resuelve y baja en paralelo, y guarda un caché global del que copia o enlaza los archivos en vez de bajarlos otra vez. Se usa de dos maneras: imitando a pip (uv venv, uv pip install -r requirements.txt, uv pip compile requirements.in --generate-hashes -o requirements.txt) o manejando el proyecto desde el pyproject.toml (uv add, uv lock, uv sync --frozen, uv run). Su uv.lock es universal: resuelve para todas las plataformas a la vez y anota qué wheel va en cada una, así que el mismo archivo sirve en la Mac del equipo y en el Linux del contenedor. También instala versiones de Python: uv python install 3.13. No viene con Python. Con uv tool install instala herramientas de línea de comandos, cada una en su entorno, como pipx.

Ejemplo. El comentario del requirements.txt del gateway de Alba dice que, en un proyecto real, ese lock se genera con uv pip compile o con pip-compile --generate-hashes; en producción se instala con uv sync --frozen o pip install -r requirements.txt.

Ver en el glosario →

pyproject.tomlpyproject.tomlLa ficha de un proyecto de Python, en la raíz de su carpeta: su nombre, su versión, qué Python necesita, de qué depende y cómo se configuran sus herramientas. Dice lo que el proyecto acepta, no lo que se instala.Más

Está escrito en TOML, un formato de texto de llaves y valores parecido al YAML, que la biblioteca estándar lee con tomllib desde Python 3.11. En [project] van name, version, requires-python y dependencies: solo las dependencias directas, casi siempre con rango. En [project.optional-dependencies] van grupos aparte, como las de pruebas. El rango dice qué versiones aceptas, pero el resolvedor escoge, el día que instalas, las más nuevas que quepan: lo que instalas lo dice el lock file. uv y Poetry leen el pyproject.toml y escriben el lock solos.

Ejemplo. Un pyproject.toml de ejemplo para el gateway: name = "gateway-alba", requires-python = ">=3.13" y dependencies = ["fastapi>=0.141", "uvicorn>=0.54", "pillow==12.3.0", "numpy>=2.5,<3"], con Pillow fija porque el preprocesamiento del entrenamiento depende de ella. (El gateway de Alba, en realidad, usa solo requirements.txt.)

Ver en el glosario →

Type hintstype hintsAnotaciones que dicen qué tipo espera cada parámetro de una función y qué tipo regresa, como ancho: int o -> int. Python las guarda pero no las revisa al correr: son documentación.Más

La sintaxis existe desde Python 3.0, y el PEP 484 (Python 3.5, 2015) acordó usarla para tipos. Python las guarda en __annotations__ y sigue de largo aunque el tipo esté mal. Las revisan programas aparte, antes de correr: mypy y pyright leen el código, siguen los tipos y avisan sin ejecutar nada, y se corren en la integración continua junto con las pruebas. El editor también las usa para autocompletar. Las que más vas a leer: list[int], dict[str, float], str | None (un texto, o nada: el revisor te obliga a manejar el None) e int = 5 (vale 5 si no lo pasas). pydantic usa las mismas anotaciones para revisar datos mientras el programa corre.

Ejemplo. def bytes_tensor(ancho: int, alto: int) -> int regresa 602,112 con 224 y 224 (3 canales × 224 × 224 píxeles × 4 bytes), el tensor en float32 de una foto de Alba. Con "224" y 1, Python no se queja: la cuenta 3 * "224" * 1 * 4 repite el texto y regresa 36 letras; mypy lo habría marcado como incompatible type "str"; expected "int".

Ver en el glosario →

pydanticpydanticUna librería que usa las anotaciones de tipo para revisar datos mientras el programa corre: describes la forma de un mensaje como una clase y pydantic revisa, convierte o rechaza cada dato que la llena.Más

Sirve para lo que ningún revisor ve antes de correr: lo que llega por la red, como el body de una request. Por omisión convierte lo que se puede convertir sin perder nada (el texto "0.93" a 0.93) y rechaza lo demás con un ValidationError; con strict=True no convierte nada. Con Field(ge=0, le=1) revisa también rangos. Desde su versión 2 (2023), su corazón es pydantic_core, escrito en Rust: una extensión nativa. FastAPI lo usa para validar cada request y responder 422 si algo no cumple; pydantic-settings hace lo mismo con las variables de entorno.

Ejemplo. Con score: float = Field(ge=0, le=1), Prediccion(label="tenis", score="0.93") guarda 0.93 como float, y score=1.7 falla con «Input should be less than or equal to 1». En el gateway de Alba, INFER_TIMEOUT_S=0.15 llega como texto y sale como un número revisado.

Ver en el glosario →

14

Chequeo

Esencial

Check

Intenta responder en tu cabeza antes de abrir cada respuesta.

  1. 1¿Dónde busca Python un módulo cuando haces import, y por qué un json.py tuyo le gana al de la biblioteca estándar?Ver respuesta

    En las carpetas de sys.path, en orden: la del script, las de PYTHONPATH, la biblioteca estándar y site-packages. Gana la primera que lo tenga. python -I deja fuera la del script.

  2. 2¿Qué diferencia hay entre una wheel y un sdist?Ver respuesta

    La wheel es un zip ya armado: instalarla es copiar. El sdist es el código fuente: pip tiene que construirlo, a veces con un compilador. Una wheel con código compilado sirve solo para la plataforma de su nombre.

  3. 3¿Por qué el mismo numpy==2.5.3 son archivos distintos en una Mac y en el contenedor?Ver respuesta

    Porque NumPy trae una extensión nativa: código compilado para un sistema, un chip y una versión de Python. La Mac baja la wheel macosx_arm64 y el contenedor, la manylinux_x86_64.

  4. 4¿Qué es una dependencia transitiva? Da un número del gateway.Ver respuesta

    Un paquete que llega porque lo pide algo que tú pediste. El gateway pide 9 y le llegan 37: 28 son transitivas, como Starlette y pydantic.

  5. 5¿Qué dice el pyproject.toml y qué dice el lock file?Ver respuesta

    El pyproject dice lo que aceptas: las directas, con rangos. El lock dice lo que instalas: todo el árbol, versiones exactas y hashes. Producción instala del lock.

  6. 6¿Qué hace de verdad «activar» un entorno virtual?Ver respuesta

    Pone su carpeta bin al principio del PATH, para que python y pip sean los del entorno. El entorno es una carpeta con su site-packages y un enlace al Python de base.

  7. 7¿Por qué una imagen con PyTorch pesa gigas y la del gateway menos de 100 MB?Ver respuesta

    torch con CUDA trae las librerías de NVIDIA: ≈ 3 GB de wheels, contra ≈ 196 MB solo para CPU. El gateway no importa torch: manda el tensor a Triton, y su imagen es la base slim más 37 dependencias, ≈ 87 MB.

Repasar los 17 conceptos de esta lección con tarjetas Sigue · 34PyTorch en lo que toca a producciónHerramientas del oficio ← 32 · La terminal y la shell