Compilar Backends
Los backends de compilación convierten tu árbol de código fuente en ruedas (wheels) y sdists distribuibles. Hatchling es el predeterminado moderno; setuptools sigue siendo común para proyectos heredados.
Receta
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"uv buildCuándo usar esto:
- Configurar cómo se compila tu paquete
- Migrar de
setup.pyapyproject.toml - Compilar paquetes con módulos de extensión
Ejemplo Funcional
[project]
name = "invoice-sdk"
version = "0.2.0"
requires-python = ">=3.14"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/invoice_sdk"]
[tool.hatch.build.targets.sdist]
include = ["src/", "tests/", "README.md"]uv build
tar -tzf dist/invoice-sdk-0.2.0-py3-none-any.whl | head
# invoice_sdk/__init__.py
# invoice_sdk/client.pyLo que esto demuestra:
- Backend
hatchling.buildespecificado en[build-system] packagesindica a hatchling dónde se encuentra el código fuenteuv buildproduce wheel y sdist- El contenido de la rueda se puede inspeccionar antes de publicarlo
Análisis Profundo
Comparación de Backends
| Backend | Mejor para | Configuración |
|---|---|---|
| hatchling | Proyectos nuevos | [tool.hatch.*] |
| setuptools | Heredado, extensiones | [tool.setuptools.*] |
| poetry-core | Proyectos de Poetry | [tool.poetry] |
| maturin | Extensiones de Rust | [tool.maturin] |
| cffi/setuptools | Extensiones de C | setup.py + pyproject |
Errores Comunes
- Configuración de
packagesfaltante - rueda vacía. Solución: configurar el descubrimiento de paquetes en[tool.hatch.build]. - Backend de compilación incorrecto para extensiones - la compilación falla. Solución: maturin para Rust, setuptools para C.
setup.pyobsoleto junto a pyproject - metadatos conflictivos. Solución: migrar completamente; eliminar setup.py.- Compilación en plataforma incorrecta - rueda específica de plataforma en el SO incorrecto. Solución: cibuildwheel para multiplataforma.
- No probar la rueda compilada - archivos faltantes descubiertos en la publicación. Solución:
pip install dist/*.whlantes de la carga.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| setuptools | Configuración existente de setuptools | Proyecto nuevo |
| flit | Paquete único simple | Monorepos complejos |
| PDM backend | Proyecto gestionado por PDM | Tienda uv/hatchling |
Preguntas Frecuentes
¿Qué backend para proyectos nuevos?
hatchling. Configuración mínima, rápido, nativo PEP 621.
¿Necesito setup.py?
No con la configuración de pyproject.toml de hatchling o setuptools.
¿Cómo compilo solo un sdist?
uv build --sdist o python -m build --sdist.
¿Puedo personalizar el contenido de la rueda?
Opciones force-include, exclude y artifacts de hatchling.
¿Cómo compilo en modo editable?
pip install -e . o uv pip install -e . - no es una compilación de rueda.
¿Qué es PEP 517?
Estándar para especificar backends de compilación en pyproject.toml.
¿Cómo añado una dependencia de compilación?
[build-system] requires = ["hatchling", "cython"].
¿Compilaciones en Monorepo?
pyproject.toml separado por paquete o espacio de trabajo uv con compilaciones por miembro.
¿Cómo verifico la rueda?
tar -tzf dist/*.whl o unzip -l dist/*.whl.
Migración de setuptools?
Mover metadatos a [project], configurar [tool.setuptools.packages.find].
Relacionado
- Conceptos Básicos de Empaquetado - introducción a la compilación
- Extensiones Nativas y Ruedas - paquetes compilados
- Publicación en PyPI - flujo de carga
- pyproject.toml Explicado
Versiones de la Pila: Esta página fue escrita para Python 3.14.0, FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, y uv 0.6+.