Conceptos básicos de entornos y empaquetado

10 ejemplos para empezar con Entornos y Empaquetado: 7 básicos y 3 intermedios.

Prerrequisitos

• Python 3.14.0 instalado (python3 --version)
• Se recomienda uv 0.6+ para instalaciones rápidas: curl -LsSf https://astral.sh/uv/install.sh | sh
• Un directorio de proyecto con un pyproject.toml (créalo con uv init si es necesario)

Ejemplos básicos

1. Crear un entorno virtual

Un entorno virtual aísla las dependencias del proyecto del Python del sistema.

python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
which python                # apunta dentro de .venv

• venv viene incluido con Python 3.14, no requiere instalación adicional
• La activación antepone .venv/bin a PATH para que pip y python sean locales al proyecto
• Desactiva con deactivate al cambiar de proyecto
• Nunca incluyas .venv/ en el control de versiones; añádelo a .gitignore

Relacionado: uv - La cadena de herramientas rápida - alternativa más rápida a venv + pip manual

2. Instalar un paquete con pip

Instala dependencias en el entorno activo.

pip install httpx
pip freeze > requirements.txt

• pip resuelve e instala desde PyPI solo en el venv activo
• pip freeze captura las versiones exactas para la reproducibilidad
• Prefiere pyproject.toml + lockfiles para proyectos nuevos (ver Explicación de pyproject.toml)
• Usa pip install -r requirements.txt para restaurar un conjunto congelado

3. Inicializar un proyecto con uv

uv reemplaza venv + pip + pip-tools en una única herramienta rápida.

uv init myapp
cd myapp
uv add httpx pydantic
uv run python -c "import httpx; print(httpx.__version__)"

• uv init crea pyproject.toml y un .venv automáticamente
• uv add escribe las dependencias en pyproject.toml y actualiza el lockfile
• uv run ejecuta dentro del entorno del proyecto sin activación manual
• uv es la cadena de herramientas recomendada por defecto para proyectos Python 3.14

Relacionado: uv - La cadena de herramientas rápida - flujo de trabajo completo de uv

4. Declarar dependencias en pyproject.toml

Los proyectos modernos declaran metadatos y dependencias en un solo archivo.

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
    "httpx>=0.28",
    "pydantic>=2",
]

• [project] es el bloque de metadatos PEP 621 que todas las herramientas de compilación leen
• requires-python evita instalaciones en intérpretes no compatibles
• Los rangos de versiones (>=) equilibran la flexibilidad con la reproducibilidad a través de lockfiles
• La configuración específica de herramientas (ruff, pytest) se encuentra en el mismo archivo bajo [tool.*]

Relacionado: Explicación de pyproject.toml - cada sección decodificada

5. Fijar con un lockfile

Los lockfiles registran las versiones exactas resueltas para instalaciones reproducibles.

uv lock
uv sync

• uv lock resuelve todas las dependencias y escribe uv.lock
• uv sync instala exactamente lo que especifica el lockfile
• Incluye el lockfile en el control de versiones; los compañeros de equipo y la CI obtienen entornos idénticos
• Vuelve a ejecutar uv lock cuando cambies las dependencias de pyproject.toml

Relacionado: Resolución de dependencias y Lockfiles - estrategias de fijación

6. Instalar múltiples versiones de Python

Prueba con varias versiones de Python en una sola máquina.

uv python install 3.13 3.14
uv venv --python 3.14
uv run --python 3.13 pytest

• uv python install descarga intérpretes sin necesidad de pyenv
• Fija el venv del proyecto a una versión específica con --python
• Ejecuta comandos contra cualquier versión instalada con uv run --python
• Haz coincidir requires-python en pyproject.toml con tu versión mínima soportada

Relacionado: Gestión de versiones de Python - pyenv y matrices de CI

7. Instalación editable para desarrollo local

Edita el código fuente y ve los cambios sin reinstalar.

uv pip install -e .
# o: pip install -e .

• -e (editable) enlaza el paquete al venv a través de un archivo .pth
• Los cambios en src/myapp/ surten efecto en la próxima importación
• Usa la disposición src/ para que las pruebas importen el paquete instalado, no la raíz del repositorio
• Requerido para monorepos con paquetes locales interdependientes

Relacionado: Instalaciones editables y paquetes locales - disposición src y monorepos

Ejemplos intermedios

8. Grupos de dependencias para desarrollo vs. producción

Separa las dependencias de tiempo de ejecución y de desarrollo.

[project]
dependencies = ["fastapi>=0.115"]
 
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9", "mypy>=1.14"]

uv sync --group dev
uv sync --no-dev   # instalación de producción solamente

• [dependency-groups] (PEP 735) reemplaza los requirements-dev.txt ad hoc
• uv sync --group dev instala herramientas de tiempo de ejecución + desarrollo
• La CI puede instalar solo lo que cada trabajo necesita
• Nunca envíes dependencias de desarrollo a contenedores de producción

9. Configurar un índice de paquetes privado

Obtén paquetes de un espejo interno o PyPI privado.

export UV_INDEX_URL=https://pypi.internal.corp/simple/
uv sync

# Alternativa pyproject.toml
[[tool.uv.index]]
url = "https://pypi.internal.corp/simple/"
default = true

• Los índices privados alojan paquetes internos y almacenan en caché el PyPI público
• Las credenciales van en ~/.netrc, variables de entorno o secretos de CI; nunca en pyproject.toml
• --index-url anula el valor por defecto para un solo comando
• Vuelve a usar el PyPI público para paquetes que no estén en el espejo internamente

Relacionado: Índices y espejos privados - autenticación y configuración de CI

10. Reproducir un entorno desde cero

Clona, instala y ejecuta en tres comandos.

git clone https://github.com/org/myapp.git && cd myapp
uv sync --frozen
uv run pytest

• --frozen falla si el lockfile está desactualizado con pyproject.toml
• Los nuevos colaboradores obtienen un entorno de trabajo en segundos
• La CI debe usar el mismo comando uv sync --frozen
• Documenta los tres comandos en tu README

Relacionado: Mejores prácticas de entornos - convenciones de equipo

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+.