Conflictos de Dependencias y Entorno

Los errores de entorno provienen de versiones de Python incompatibles, archivos de bloqueo divergentes, paquetes enmascarados en PYTHONPATH e instalaciones editables que apuntan a un checkout incorrecto. Los síntomas son errores de importación, caídas de ABI y pruebas que pasan localmente pero fallan en CI.

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

python3 --version          # esperar 3.14.0 en entornos alineados con producción
which python3
uv sync                    # instalar desde uv.lock
uv run pytest
python -c "import mypkg; print(mypkg.__file__)"

Cuándo recurrir a esto:

ModuleNotFoundError para un paquete que "acabas de instalar"
ImportError: DLL load failed / ruedas binarias incompatibles
CI falla mientras el portátil pasa (o viceversa)
Dos proyectos necesitan versiones conflictivas de la misma biblioteca

Ejemplo de Trabajo

# diagnose.sh - ejecutar desde la raíz del repositorio
set -euo pipefail
 
echo "=== Python ==="
python3 --version
which python3
 
echo "=== Entorno Virtual ==="
echo "${VIRTUAL_ENV:-no activado}"
 
echo "=== Instalación desde archivo de bloqueo ==="
uv sync --frozen
 
echo "=== Ubicación del paquete ==="
uv run python -c "import orders; print(orders.__file__)"
 
echo "=== Distribuciones instaladas (principales) ==="
uv pip list | head -20
 
echo "=== pip check ==="
uv pip check

# pyproject.toml - fijar tiempo de ejecución y aislar grupos
[project]
name = "orders"
requires-python = ">=3.14"
dependencies = ["fastapi>=0.115", "pydantic>=2"]
 
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9"]
 
[tool.uv]
dev-dependencies = ["pytest>=8", "ruff>=0.9"]

# verify_imports.py - prueba de humo de CI
import importlib
import sys
 
REQUIRED = ("fastapi", "pydantic", "orders")
 
def main() -> None:
    print("ejecutable:", sys.executable)
    print("versión:", sys.version.replace("\n", " "))
    for name in REQUIRED:
        mod = importlib.import_module(name)
        print(f"{name} -> {getattr(mod, '__file__', mod)}")
 
if __name__ == "__main__":
    main()

Lo que esto demuestra:

Versión y ruta impresas antes de depurar importaciones
uv sync --frozen falla si el archivo de bloqueo está desactualizado con pyproject.toml
requires-python documenta el umbral del intérprete compatible
El script de prueba de importación detecta un paquete incorrecto en la ruta temprano

Análisis Profundo

Cómo Funciona

Los entornos virtuales aíslan site-packages por proyecto
Los archivos de bloqueo fijan versiones transitivas; pip install suelto no lo hace
Las ruedas binarias se vinculan a etiquetas de ABI de Python (cp314 vs cp313)
Las instalaciones editables (-e .) enlazan simbólicamente al código fuente; el cwd incorrecto significa código incorrecto

Lista de Verificación de Conflictos

Señal	Causa probable	Solución
Paquete antiguo a pesar de la actualización	venv incorrecto activo	`deactivate`; activar `.venv`
Dos versiones en `pip list`	sitio del sistema + usuario	venv puro; `pip install --force-reinstall`
Rueda `cpython-312` en 3.14	rueda incorrecta	regenerar bloqueo en Python de destino
Importación desde ruta inesperada	enmascaramiento de PYTHONPATH	eliminar; corregir empaquetado
Poetry + uv mezclados	dos herramientas de bloqueo	estandarizar en uv 0.6+

Notas de Python

# reproducir CI localmente con contenedor
docker run --rm -v "$PWD:/app" -w /app python:3.14.0-bookworm \
  bash -lc "pip install uv && uv sync --frozen && uv run pytest"

Trampas

pip install global - contamina el Python base; rompe otros proyectos. Solución: venv por proyecto; nunca instale dependencias de la aplicación globalmente.
.venv confirmado - binarios específicos de la plataforma en git. Solución: gitignore; documentar uv sync en README.
Extras opcionales no instalados en CI - pip install . sin el extra [ml] falta torch. Solución: documentar extras; CI instala los grupos necesarios.
Diferente cwd en el ejecutor de pruebas del IDE - importa el módulo local enmascarado json.py. Solución: renombrar enmascaramientos; diseño de src.
Instalación editable obsoleta después de renombrar - nombre de paquete antiguo en caché. Solución: reinstalar editable; limpiar *.egg-link.
Mezcla de Conda + pip - ABIs rotas de numpy/openssl. Solución: una herramienta por entorno; stack de conda O uv/pip.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`uv` lock + sync	entornos rápidos y reproducibles	la organización exige solo poetry (puentear con cuidado)
`pip-tools` compile	tiendas `pip-tools` existentes	nuevo proyecto sin restricciones
Desarrollo solo con Docker	paridad estricta con producción	se necesita iteración rápida en el portátil
Matrices `tox`/`nox`	bibliotecas multiversión	microservicios de versión única

Preguntas Frecuentes

¿Por qué uv sync soluciona "funciona en mi máquina"?

Todos instalan el mismo grafo resuelto desde uv.lock en la misma ABI de Python. La deriva se muestra como un error de bloqueo en lugar de importaciones misteriosas.

¿Debería CI usar --frozen?

Sí en pipelines de lanzamiento. Falla cuando pyproject.toml cambia sin actualizar el archivo de bloqueo, evitando actualizaciones silenciosas.

¿Cómo depuro una ruta de módulo incorrecta?

python -c "import m; print(m.__file__)" y comparar con la ruta esperada de site-packages o la ruta editable de src/.

¿Pueden dos proyectos compartir un venv?

Evítalo. Vuelven a aparecer pines conflictivos y enmascaramiento de importaciones. Un venv por repositorio o usar el espacio de trabajo de uv con miembros explícitos.

¿Qué pasa si las ruedas CUDA de PyTorch difieren por máquina?

Documentar índices de extras opcionales en README. Los trabajos solo de CPU de CI instalan el índice de CPU; las máquinas GPU instalan el extra específico de la plataforma.

¿Cómo fijo Python 3.14 en Docker?

Usa python:3.14.0-bookworm (o slim) y haz coincidir requires-python en pyproject.toml.

¿Necesita ruff el mismo venv?

Ejecuta ruff 0.9+ a través de uv run ruff para que las reglas y las correcciones automáticas vean las stubs de terceros instaladas de manera consistente.

¿Cómo soluciono los fallos de pip check?

uv pip check informa pines incompatibles. Regenera el bloqueo desde un venv limpio; elimina las anulaciones manuales de pip install en Dockerfile.

¿Qué pasa con el Python del sistema en macOS?

Usa python3 desde .venv después de uv venv. Los Python de Homebrew/sistema están bien como intérpretes base, no como destinos de instalación.

¿Cómo ayudan los grupos de dependencias opcionales?

Mantén pilas de ML pesadas opcionales ([project.optional-dependencies]) para que los servicios de API no instalen PyTorch en cada imagen.

¿Puedo eliminar uv.lock y regenerar?

Sí, al actualizar versiones principales deliberadamente. Confirma el nuevo bloqueo y ejecuta la matriz completa de CI después.

¿Cómo ocurren los conflictos entre IDE y CLI?

El IDE apunta a un intérprete diferente al de la terminal. Configura explícitamente el intérprete del espacio de trabajo a .venv/bin/python.

Relacionado

Configuración y Ajustes - variables de entorno vs paquetes
Diseño de src y Estructura de Paquetes - instalar antes de probar
Escenarios de Importación Circular - errores de importación que parecen dependencias faltantes
Lista de Verificación de Auditoría de Código - archivo de bloqueo y elementos de auditoría
Herramientas de Depuración - inspeccionar sys.path en pdb

Versiones de pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), 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+.

Conflictos de Dependencias y Entorno

Receta

Tarjeta de receta de referencia rápida, lista para copiar y pegar.

python3 --version          # esperar 3.14.0 en entornos alineados con producción
which python3
uv sync                    # instalar desde uv.lock
uv run pytest
python -c "import mypkg; print(mypkg.__file__)"

Cuándo recurrir a esto:

ModuleNotFoundError para un paquete que "acabas de instalar"
ImportError: DLL load failed / ruedas binarias incompatibles
CI falla mientras el portátil pasa (o viceversa)
Dos proyectos necesitan versiones conflictivas de la misma biblioteca

Ejemplo de Trabajo

# diagnose.sh - ejecutar desde la raíz del repositorio
set -euo pipefail
 
echo "=== Python ==="
python3 --version
which python3
 
echo "=== Entorno Virtual ==="
echo "${VIRTUAL_ENV:-no activado}"
 
echo "=== Instalación desde archivo de bloqueo ==="
uv sync --frozen
 
echo "=== Ubicación del paquete ==="
uv run python -c "import orders; print(orders.__file__)"
 
echo "=== Distribuciones instaladas (principales) ==="
uv pip list | head -20
 
echo "=== pip check ==="
uv pip check

# pyproject.toml - fijar tiempo de ejecución y aislar grupos
[project]
name = "orders"
requires-python = ">=3.14"
dependencies = ["fastapi>=0.115", "pydantic>=2"]
 
[dependency-groups]
dev = ["pytest>=8", "ruff>=0.9"]
 
[tool.uv]
dev-dependencies = ["pytest>=8", "ruff>=0.9"]

# verify_imports.py - prueba de humo de CI
import importlib
import sys
 
REQUIRED = ("fastapi", "pydantic", "orders")
 
def main() -> None:
    print("ejecutable:", sys.executable)
    print("versión:", sys.version.replace("\n", " "))
    for name in REQUIRED:
        mod = importlib.import_module(name)
        print(f"{name} -> {getattr(mod, '__file__', mod)}")
 
if __name__ == "__main__":
    main()

Lo que esto demuestra:

Versión y ruta impresas antes de depurar importaciones
uv sync --frozen falla si el archivo de bloqueo está desactualizado con pyproject.toml
requires-python documenta el umbral del intérprete compatible
El script de prueba de importación detecta un paquete incorrecto en la ruta temprano

Análisis Profundo

Cómo Funciona

Los entornos virtuales aíslan site-packages por proyecto
Los archivos de bloqueo fijan versiones transitivas; pip install suelto no lo hace
Las ruedas binarias se vinculan a etiquetas de ABI de Python (cp314 vs cp313)
Las instalaciones editables (-e .) enlazan simbólicamente al código fuente; el cwd incorrecto significa código incorrecto

Lista de Verificación de Conflictos

Señal	Causa probable	Solución
Paquete antiguo a pesar de la actualización	venv incorrecto activo	`deactivate`; activar `.venv`
Dos versiones en `pip list`	sitio del sistema + usuario	venv puro; `pip install --force-reinstall`
Rueda `cpython-312` en 3.14	rueda incorrecta	regenerar bloqueo en Python de destino
Importación desde ruta inesperada	enmascaramiento de PYTHONPATH	eliminar; corregir empaquetado
Poetry + uv mezclados	dos herramientas de bloqueo	estandarizar en uv 0.6+

Notas de Python

# reproducir CI localmente con contenedor
docker run --rm -v "$PWD:/app" -w /app python:3.14.0-bookworm \
  bash -lc "pip install uv && uv sync --frozen && uv run pytest"

Trampas

pip install global - contamina el Python base; rompe otros proyectos. Solución: venv por proyecto; nunca instale dependencias de la aplicación globalmente.
.venv confirmado - binarios específicos de la plataforma en git. Solución: gitignore; documentar uv sync en README.
Extras opcionales no instalados en CI - pip install . sin el extra [ml] falta torch. Solución: documentar extras; CI instala los grupos necesarios.
Diferente cwd en el ejecutor de pruebas del IDE - importa el módulo local enmascarado json.py. Solución: renombrar enmascaramientos; diseño de src.
Instalación editable obsoleta después de renombrar - nombre de paquete antiguo en caché. Solución: reinstalar editable; limpiar *.egg-link.
Mezcla de Conda + pip - ABIs rotas de numpy/openssl. Solución: una herramienta por entorno; stack de conda O uv/pip.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`uv` lock + sync	entornos rápidos y reproducibles	la organización exige solo poetry (puentear con cuidado)
`pip-tools` compile	tiendas `pip-tools` existentes	nuevo proyecto sin restricciones
Desarrollo solo con Docker	paridad estricta con producción	se necesita iteración rápida en el portátil
Matrices `tox`/`nox`	bibliotecas multiversión	microservicios de versión única

Preguntas Frecuentes

¿Por qué uv sync soluciona "funciona en mi máquina"?

Todos instalan el mismo grafo resuelto desde uv.lock en la misma ABI de Python. La deriva se muestra como un error de bloqueo en lugar de importaciones misteriosas.

¿Debería CI usar --frozen?

Sí en pipelines de lanzamiento. Falla cuando pyproject.toml cambia sin actualizar el archivo de bloqueo, evitando actualizaciones silenciosas.

¿Cómo depuro una ruta de módulo incorrecta?

python -c "import m; print(m.__file__)" y comparar con la ruta esperada de site-packages o la ruta editable de src/.

¿Pueden dos proyectos compartir un venv?

Evítalo. Vuelven a aparecer pines conflictivos y enmascaramiento de importaciones. Un venv por repositorio o usar el espacio de trabajo de uv con miembros explícitos.

¿Qué pasa si las ruedas CUDA de PyTorch difieren por máquina?

Documentar índices de extras opcionales en README. Los trabajos solo de CPU de CI instalan el índice de CPU; las máquinas GPU instalan el extra específico de la plataforma.

¿Cómo fijo Python 3.14 en Docker?

Usa python:3.14.0-bookworm (o slim) y haz coincidir requires-python en pyproject.toml.

¿Necesita ruff el mismo venv?

Ejecuta ruff 0.9+ a través de uv run ruff para que las reglas y las correcciones automáticas vean las stubs de terceros instaladas de manera consistente.

¿Cómo soluciono los fallos de pip check?

uv pip check informa pines incompatibles. Regenera el bloqueo desde un venv limpio; elimina las anulaciones manuales de pip install en Dockerfile.

¿Qué pasa con el Python del sistema en macOS?

Usa python3 desde .venv después de uv venv. Los Python de Homebrew/sistema están bien como intérpretes base, no como destinos de instalación.

¿Cómo ayudan los grupos de dependencias opcionales?

Mantén pilas de ML pesadas opcionales ([project.optional-dependencies]) para que los servicios de API no instalen PyTorch en cada imagen.

¿Puedo eliminar uv.lock y regenerar?

Sí, al actualizar versiones principales deliberadamente. Confirma el nuevo bloqueo y ejecuta la matriz completa de CI después.

¿Cómo ocurren los conflictos entre IDE y CLI?

El IDE apunta a un intérprete diferente al de la terminal. Configura explícitamente el intérprete del espacio de trabajo a .venv/bin/python.

Relacionado

Configuración y Ajustes - variables de entorno vs paquetes
Diseño de src y Estructura de Paquetes - instalar antes de probar
Escenarios de Importación Circular - errores de importación que parecen dependencias faltantes
Lista de Verificación de Auditoría de Código - archivo de bloqueo y elementos de auditoría
Herramientas de Depuración - inspeccionar sys.path en pdb

Versiones de pila: Esta página se escribió para Python 3.14.0 (estable 3.14, mantenimiento 3.13), 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+.

Conflictos de Dependencias y Entorno

Buscar en la documentación

Conflictos de Dependencias y Entorno