Cómo crear un paquete Python y publicarlo en PyPI

Publicar una librería propia en PyPI (Python Package Index) permite que cualquier persona la instale con un simple pip install. El proceso implica estructurar correctamente el proyecto, configurar los metadatos, generar los archivos de distribución y subirlos al índice. A continuación se explica paso a paso cómo hacerlo usando las herramientas actuales del ecosistema Python.

1. Estructura del proyecto

Antes de empezar, conviene organizar el proyecto siguiendo el llamado src layout, recomendado por la comunidad porque evita errores comunes de importación durante las pruebas:

mi_paquete/
├── src/
│   └── mi_paquete/
│       ├── __init__.py
│       └── core.py
├── tests/
│   └── test_core.py
├── pyproject.toml
├── README.md
├── LICENSE
└── .gitignore

Contenido de ejemplo

# src/mi_paquete/core.py

def saludar(nombre: str) -> str:
    """Devuelve un saludo personalizado."""
    return f"¡Hola, {nombre}!"

# src/mi_paquete/__init__.py

from .core import saludar

__version__ = "0.1.0"
__all__ = ["saludar"]

2. Configurar pyproject.toml

Desde 2021, pyproject.toml es el estándar para definir metadatos y configuración de build, reemplazando al antiguo setup.py. Un ejemplo usando el backend setuptools:

[build-system]
requires = ["setuptools>=68.0"]
build-backend = "setuptools.build_meta"

[project]
name = "mi-paquete"
version = "0.1.0"
description = "Una breve descripción de mi paquete"
readme = "README.md"
requires-python = ">=3.9"
license = { file = "LICENSE" }
authors = [
    { name = "Tu Nombre", email = "tu@email.com" }
]
keywords = ["ejemplo", "paquete", "pypi"]
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
dependencies = [
    "requests>=2.28",
]

[project.urls]
Homepage = "https://github.com/tu-usuario/mi-paquete"
Issues = "https://github.com/tu-usuario/mi-paquete/issues"

[project.optional-dependencies]
dev = ["pytest", "build", "twine"]

El nombre indicado en name debe estar disponible en PyPI; conviene comprobarlo antes en pypi.org para evitar conflictos.

3. Elegir una licencia

Es recomendable incluir un archivo LICENSE con una licencia reconocida (MIT, Apache 2.0, GPL, etc.). Esto define legalmente cómo otras personas pueden usar, modificar y distribuir el código.

4. Crear un entorno virtual e instalar herramientas de build

python -m venv venv
source venv/bin/activate   # En Windows: venv\Scripts\activate

pip install --upgrade pip
pip install build twine

• build: genera los archivos de distribución (sdist y wheel).
• twine: sube esos archivos a PyPI de forma segura.

5. Generar los archivos de distribución

python -m build

Este comando crea una carpeta dist/ con dos archivos:

• mi_paquete-0.1.0.tar.gz — distribución de código fuente (sdist).
• mi_paquete-0.1.0-py3-none-any.whl — distribución binaria (wheel), más rápida de instalar.

6. Probar en TestPyPI antes de publicar

Para evitar errores irreversibles en el índice oficial, es buena práctica subir primero el paquete a TestPyPI, un entorno de pruebas idéntico a PyPI:

twine upload --repository testpypi dist/*

Luego se puede instalar desde ahí para verificar que todo funciona correctamente:

pip install --index-url https://test.pypi.org/simple/ mi-paquete

7. Crear una cuenta y un token API en PyPI

Es necesario registrarse en pypi.org y generar un token de API desde la sección de configuración de la cuenta (Account settings → API tokens). Por seguridad, ya no se recomienda usar usuario y contraseña directamente.

El token se puede guardar en un archivo ~/.pypirc:

[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmc...tu-token-completo

8. Publicar el paquete en PyPI

Una vez verificado en TestPyPI, se sube la versión definitiva al índice oficial:

twine upload dist/*

Tras unos segundos, el paquete estará disponible públicamente y cualquier persona podrá instalarlo con:

pip install mi-paquete

9. Versionado y publicación de actualizaciones

Cada vez que se publique una nueva versión, hay que:

1. Incrementar el número de versión en pyproject.toml (siguiendo versionado semántico: MAYOR.MENOR.PARCHE).
2. Volver a generar los archivos con python -m build.
3. Subir la nueva versión con twine upload dist/*.

PyPI no permite resubir una versión ya publicada con el mismo número, ni siquiera si se elimina; cada cambio requiere incrementar la versión.

10. Buenas prácticas adicionales

• Incluye un README.md claro: PyPI lo muestra como descripción del proyecto.
• Añade pruebas automatizadas con pytest y, si es posible, integración continua (GitHub Actions, por ejemplo).
• Usa classifiers en pyproject.toml para mejorar la visibilidad y filtrado en PyPI.
• Considera automatizar la publicación con un workflow de CI/CD que ejecute build y twine upload al crear un nuevo tag de versión.
• Verifica que el nombre del paquete no infrinja marcas registradas ni se confunda con otros proyectos existentes.

Conclusión

Crear y publicar un paquete en PyPI es un proceso accesible una vez se entiende la estructura básica: organizar el código en un src layout, definir los metadatos en pyproject.toml, generar los artefactos con build y subirlos con twine. Probar primero en TestPyPI evita errores costosos y, a partir de ahí, mantener buenas prácticas de versionado y documentación facilita que el paquete sea útil y confiable para otros desarrolladores.