Publicar un paquete en PyPI permite que otras personas instalen tu proyecto con pip install nombre-paquete. El proceso moderno utiliza un archivo pyproject.toml, una herramienta de construcción y un cliente de subida como Twine. Aunque el primer lanzamiento puede parecer complejo, la estructura es repetible y ayuda a convertir código reutilizable en una dependencia profesional.
Antes de publicar, conviene entender la diferencia entre módulos y paquetes en Python, así como el funcionamiento general de las bibliotecas de Python. PyPI no corrige una estructura desordenada: simplemente distribuye lo que construyes.
Qué es PyPI
PyPI, Python Package Index, es el repositorio público principal del ecosistema Python. pip consulta este índice para localizar versiones, archivos wheel y distribuciones de código fuente. Publicar allí facilita la instalación, actualización y resolución de dependencias.
Antes del repositorio principal es recomendable usar TestPyPI, un entorno separado para practicar subidas sin ocupar nombres ni versiones reales.
Estructura mínima del proyecto
mi_paquete/
├── pyproject.toml
├── README.md
├── LICENSE
├── src/
│ └── mi_paquete/
│ ├── __init__.py
│ └── texto.py
└── tests/
└── test_texto.pyLa estructura src evita que las pruebas importen accidentalmente el código desde la carpeta del proyecto en lugar de la versión instalada. Esto revela errores de empaquetado antes de publicar.
Crear el código del paquete
# src/mi_paquete/texto.py
def limpiar_espacios(texto: str) -> str:
return " ".join(texto.split())# src/mi_paquete/__init__.py
from .texto import limpiar_espacios
__all__ = ["limpiar_espacios"]La API pública debe ser pequeña, clara y estable. No exportes cada función interna sin una razón, porque los usuarios pueden comenzar a depender de detalles que luego serán difíciles de cambiar.
Configurar pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "mi-paquete-ejemplo"
version = "0.1.0"
description = "Utilidades sencillas para procesar texto"
readme = "README.md"
requires-python = ">>=3.10"
license = {text = "MIT"}
authors = [
{name = "Tu nombre", email = "tu@email.com"}
]
dependencies = []
[project.urls]
Homepage = "https://example.com"
Repository = "https://github.com/usuario/mi-paquete"El nombre de distribución en PyPI puede contener guiones, mientras que el nombre importado suele utilizar guiones bajos. Comprueba que el nombre esté disponible y evita imitar proyectos conocidos.
Usar un entorno virtual
Crea un entorno aislado para que las herramientas de publicación no se mezclen con dependencias globales. La guía de entornos virtuales con venv explica la activación en Windows, macOS y Linux.
python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# macOS o Linux
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install build twineEscribir un README útil
El README será la página principal del proyecto en PyPI. Debe explicar qué problema resuelve, cómo se instala, cuál es el ejemplo mínimo y dónde reportar errores.
# Mi paquete ejemplo
Instalación:
```bash
pip install mi-paquete-ejemplo
```
Uso:
```python
from mi_paquete import limpiar_espacios
print(limpiar_espacios("hola mundo"))
```Evita prometer funciones que aún no existen. Incluye compatibilidad de versiones, estado del proyecto y advertencias relevantes.
Probar antes de construir
Ejecuta pruebas en un entorno limpio. Un paquete que funciona únicamente dentro de su repositorio puede fallar después de instalado.
python -m pip install -e .
python -m pytestEl modo editable facilita el desarrollo, pero también debes probar el wheel final. La automatización con GitHub Actions para proyectos Python ayuda a ejecutar tests en varias versiones del intérprete.
Construir el paquete
python -m buildEl comando crea la carpeta dist con una distribución de código fuente y un archivo wheel. No edites estos archivos manualmente.
dist/
├── mi_paquete_ejemplo-0.1.0-py3-none-any.whl
└── mi_paquete_ejemplo-0.1.0.tar.gzComprobar los archivos con Twine
python -m twine check dist/*Esta comprobación detecta problemas de metadatos y renderizado del README. También puedes inspeccionar el contenido del wheel como archivo ZIP para confirmar que no incluyes secretos, archivos temporales o datos innecesarios.
Crear cuentas y tokens
Crea una cuenta separada en TestPyPI y otra en PyPI. Activa autenticación multifactor y genera tokens de API. No guardes el token dentro del repositorio, del código ni del historial del terminal compartido.
Cuando Twine solicite el usuario, utiliza __token__. La contraseña será el token completo. Para automatización, almacena el secreto en el proveedor de CI y limita su alcance cuando sea posible.
Subir primero a TestPyPI
python -m twine upload --repository testpypi dist/*Después instala el paquete desde el índice de pruebas en un entorno nuevo:
python -m venv prueba
source prueba/bin/activate
python -m pip install --index-url https://test.pypi.org/simple/ --no-deps mi-paquete-ejemploEl parámetro --no-deps evita problemas porque TestPyPI no contiene necesariamente todas las dependencias del índice principal.
Publicar en PyPI
python -m twine upload dist/*Una versión publicada no debe sobrescribirse. Si descubres un error, corrige el proyecto, aumenta la versión y genera nuevos archivos. Este comportamiento protege la reproducibilidad de instalaciones existentes.
Versionado y lanzamientos
Una estrategia habitual es el versionado semántico: cambios compatibles incrementan la versión menor; correcciones incrementan el parche; cambios incompatibles incrementan la versión mayor. Documenta las modificaciones en un changelog y crea etiquetas de Git.
Herramientas como Poetry pueden gestionar dependencias, construcción y publicación, pero comprender el flujo estándar con pyproject.toml, build y Twine sigue siendo valioso.
Errores frecuentes
Los problemas más comunes son reutilizar una versión ya publicada, elegir un nombre ocupado, olvidar archivos dentro del wheel, declarar dependencias incorrectas, incluir credenciales o publicar desde un entorno sucio. También es frecuente confundir el nombre del paquete en PyPI con el nombre usado en import.
Evita ejecutar la subida hasta que hayas instalado y probado el wheel en un entorno completamente nuevo. Esa comprobación reproduce mejor la experiencia real del usuario.
Fuentes oficiales
La guía oficial de empaquetado de proyectos Python describe la estructura moderna, TestPyPI, construcción y subida. La documentación oficial de Twine explica autenticación, repositorios y opciones de publicación.
Conclusión
Publicar en PyPI exige preparar una estructura correcta, declarar metadatos, probar el paquete, construir distribuciones y subirlas con credenciales seguras. TestPyPI reduce el riesgo del primer lanzamiento. Cuando automatizas pruebas y respetas versiones inmutables, tu paquete resulta más confiable para quienes lo instalan.
