Gestión de Versiones de Python
Ejecutar múltiples versiones de Python en una sola máquina te permite desarrollar en la última versión, probar la compatibilidad hacia atrás y replicar exactamente los intérpretes de producción.
Receta
# uv (recomendado)
uv python install 3.13 3.14
uv python pin 3.14
# pyenv (alternativa)
pyenv install 3.14.0
pyenv local 3.14.0Cuándo usar esto:
- Probar contra Python 3.13 y 3.14 en el mismo repositorio
- Replicar localmente la versión del intérprete de producción
- Contribuir a bibliotecas con amplio soporte
requires-python
Ejemplo de Trabajo
# Instalar intérpretes
uv python install 3.13 3.14
# Fijar proyecto a 3.14
cd myproject
uv python pin 3.14
cat .python-version # 3.14
# Probar en 3.13 sin cambiar el pin
uv run --python 3.13 pytest
# Matriz CI multiversión (extracto de GitHub Actions)strategy:
matrix:
python-version: ["3.13", "3.14"]
steps:
- uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
- run: pip install -e ".[dev]" && pytestLo que esto demuestra:
uv python installdescarga intérpretes sin gestores de paquetes del sistema.python-versionfija el valor predeterminado para un árbol de directoriosuv run --pythonejecuta un solo comando contra otra versión- Las matrices CI verifican la compatibilidad entre las versiones admitidas
Análisis Profundo
Cómo Funciona
- uv python almacena los intérpretes en
~/.local/share/uv/python/y crea enlaces simbólicos bajo demanda - pyenv compila o descarga intérpretes en
~/.pyenv/versions/y utiliza "shims" parapythona través de PATH requires-pythonenpyproject.tomldeclara el rango admitido- tox/nox automatizan las ejecuciones de pruebas multiversión localmente y en CI
Herramientas de Selección de Versión
| Herramienta | Instalar | Fijar por proyecto | Velocidad |
|---|---|---|---|
| uv python | uv python install | .python-version | Rápido |
| pyenv | pyenv install | .python-version | Moderado |
| deadsnakes PPA | apt install python3.14 | Manual | A nivel de sistema |
| asdf | asdf install python | .tool-versions | Moderado |
Notas de Python
# pyproject.toml - declara el rango admitido
[project]
requires-python = ">=3.13"# tox.ini para pruebas locales multiversión
[tox]
envlist = py313,py314Errores Comunes
- Python del sistema para proyectos - falla cuando el SO actualiza Python. Solución: usa siempre un venv de proyecto con un intérprete fijado.
.python-versionno confirmado - los compañeros de equipo usan versiones diferentes. Solución: confirma.python-versiono documéntalo enpyproject.toml.- Probar solo en la última versión - sorprende a los usuarios en versiones anteriores. Solución: matriz CI que cubra el límite inferior de
requires-python. - Fallos de compilación de pyenv en macOS - faltan las herramientas de línea de comandos de Xcode. Solución:
xcode-select --install; o usauv python install(binarios precompilados). - Mezclar pines de pyenv y uv - conflictos de shims. Solución: estandariza en un solo gestor de versiones por proyecto.
Alternativas
| Alternativa | Usar cuando | No usar cuando |
|---|---|---|
| Docker por versión | Reproducción exacta de producción | Iteración local rápida |
| Nix/devcontainers | Entornos idénticos para todo el equipo | Aplicaciones simples de una sola versión |
| Paquetes del sistema solamente | Imágenes de despliegue de servidor | Desarrollo local |
Preguntas Frecuentes
uv python vs pyenv - ¿cuál debería usar?
uv python es más rápido (binarios precompilados) y se integra con los flujos de trabajo de uv. pyenv tiene un ecosistema de plugins más amplio. Proyectos nuevos: uv.
¿Cómo compruebo la versión activa de Python?
python --version o uv run python --version dentro de un proyecto.
¿Puedo ejecutar código de 3.14 en 3.13?
Solo si evitas la sintaxis y las API exclusivas de 3.14. Prueba explícitamente en 3.13.
¿Qué archivo fija la versión?
.python-version (uv/pyenv), pyproject.toml requires-python, o .tool-versions (asdf).
¿Cómo actualizo la versión de Python del proyecto?
Instala la nueva versión, actualiza .python-version, actualiza requires-python, recrea el venv y ejecuta las pruebas.
¿Necesito múltiples versiones para bibliotecas?
Sí. Las bibliotecas deben probarse con cada versión en requires-python.
¿Cómo encaja Python 3.14 free-threaded?
Instala la variante 3.14t con uv para pruebas sin GIL. La mayoría de las aplicaciones todavía usan la compilación predeterminada.
¿Puede la CI usar uv para instalar Python?
Sí: uv python install 3.14 en GitHub Actions sin setup-python.
¿Qué pasa con Windows?
uv proporciona binarios para Windows. pyenv-win es el port de pyenv para Windows.
¿Cómo listo las versiones instaladas?
uv python list o pyenv versions.
Relacionado
- uv - La Toolchain Rápida - gestión integrada de versiones
- Conceptos Básicos de Entornos y Empaquetado - fundamentos de venv
- tox / nox - automatización de pruebas multiversión
- Mejores Prácticas de Entornos - política de versiones
Versiones de la Pila: Esta página se escribió 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+.