Instalaciones Editables y Paquetes Locales

Las instalaciones editables enlazan tu árbol de código fuente al entorno virtual para que los cambios en el código surtan efecto inmediatamente. Combinado con el diseño src/, esto proporciona importaciones fiables en desarrollo y pruebas.

Receta

# Proyecto con diseño src/
uv pip install -e .
# o: pip install -e .
 
# Dependencia de ruta local en pyproject.toml
# dependencies = ["my-utils @ file:///ruta/a/my-utils"]

Cuándo usar esto:

Desarrollo activo en una biblioteca o paquete de aplicación
Monorepos con paquetes locales interdependientes
Pruebas que deben importar el paquete instalado, no la raíz del repositorio

Ejemplo de Trabajo

myapp/
├── pyproject.toml
├── src/
│   └── myapp/
│       ├── __init__.py
│       └── core.py
└── tests/
    └── test_core.py

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]

uv pip install -e ".[dev]"
uv run pytest

# tests/test_core.py
from myapp.core import greet
 
def test_greet():
    assert greet("Ada") == "Hello, Ada!"

Lo que esto demuestra:

El diseño src/ evita importaciones accidentales desde la raíz del repositorio
La instalación editable hace que import myapp resuelva a src/myapp/
Las pruebas ejercitan la misma ruta de importación que usa producción
Los cambios en core.py son visibles en la siguiente ejecución de pruebas sin reinstalar

Profundización

Cómo Funciona

pip install -e . escribe un archivo .pth en el venv apuntando a src/
El backend de compilación descubre paquetes a través de la configuración de pyproject.toml
Las dependencias de ruta (my-utils @ file://...) enlazan paquetes locales al árbol de dependencias
Los espacios de trabajo de uv coordinan múltiples paquetes editables en un monorepo

Diseño `src` vs Diseño Plano

Diseño	Riesgo de importación	Recomendado
`src/myapp/`	Bajo (requiere instalación)	Sí
`myapp/` en la raíz	Las pruebas importan código no instalado	No

Notas de Python

# Espacio de trabajo uv para monorepos
[tool.uv.workspace]
members = ["packages/*"]
 
# packages/myapp/pyproject.toml
[project]
name = "myapp"
dependencies = ["my-utils"]
 
# packages/my-utils/pyproject.toml
[project]
name = "my-utils"

uv sync   # instala todos los miembros del espacio de trabajo de forma editable

Errores Comunes

Las pruebas pasan sin instalación (diseño plano) - CI falla porque el paquete nunca se compiló. Solución: adopta el diseño src/; siempre ejecuta pip install -e . antes de probar.
Instalación editable después de renombrar un paquete - .pth obsoleto apunta a la ruta antigua. Solución: reinstala: uv pip install -e . --force-reinstall.
Dependencias de ruta absoluta en pyproject.toml - falla en otras máquinas. Solución: usa espacios de trabajo uv o dependencias de ruta relativa para monorepos.
Falta __init__.py - los paquetes de namespace pueden confundir el descubrimiento editable. Solución: incluye __init__.py a menos que uses intencionadamente paquetes de namespace.
Publicar un paquete solo editable - pip install desde PyPI necesita una rueda real. Solución: editable es para desarrollo; usa uv build para distribución.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`PYTHONPATH=src`	Hack rápido, sin instalación	Producción o CI (frágil)
Instalación regular (`pip install .`)	Verificar el paquete compilado	Desarrollo activo
Espacio de trabajo uv	Monorepo con 2+ paquetes	Aplicaciones de un solo paquete

Preguntas Frecuentes

¿Qué significa -e?

Editable. El paquete instalado enlaza de vuelta a tu directorio de código fuente.

¿Necesito reinstalar después de añadir un nuevo módulo?

No para nuevos archivos .py dentro de un paquete existente. Sí si añades un nuevo paquete de nivel superior o cambias los puntos de entrada.

¿Por qué usar el diseño src/?

Obliga a las pruebas a importar el paquete instalado, detectando errores de empaquetado antes del lanzamiento.

¿Cómo funcionan las dependencias de ruta de monorepo?

Espacios de trabajo uv o dependencies = ["sibling @ file:///${PROJECT_ROOT}/packages/sibling"] con rutas relativas.

¿Puedo instalar una dependencia de forma editable?

Sí: uv pip install -e ../my-utils o declárala como miembro del espacio de trabajo.

¿Editable funciona con Poetry?

Sí: poetry install instala el proyecto actual de forma editable por defecto.

¿Qué pasa con los archivos de datos en modo editable?

Los datos del paquete deben declararse en pyproject.toml ([tool.hatch.build.targets.wheel.force-include]). Las ediciones de código fuente a los archivos de datos se capturan inmediatamente.

¿Cómo verifico la ruta de instalación?

python -c "import myapp; print(myapp.__file__)" debería apuntar a src/myapp/.

¿Editable en Docker?

Monta el código fuente como un volumen e instala pip install -e . en el contenedor para desarrollo con recarga en vivo.

¿Puedo mezclar dependencias editables y regulares?

Sí. Solo tu proyecto (y los hermanos del espacio de trabajo) son editables; las dependencias de PyPI se instalan normalmente.

Relacionado

pyproject.toml Explicado - configuración del paquete
uv - La Cadena de Herramientas Rápida - soporte de espacio de trabajo
Conceptos Básicos de Empaquetado - ruedas y sdists
Mejores Prácticas de Entornos - convenciones de diseño

Versiones de Stack: Esta página fue escrita 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+.

Instalaciones Editables y Paquetes Locales

Receta

# Proyecto con diseño src/
uv pip install -e .
# o: pip install -e .
 
# Dependencia de ruta local en pyproject.toml
# dependencies = ["my-utils @ file:///ruta/a/my-utils"]

Cuándo usar esto:

Desarrollo activo en una biblioteca o paquete de aplicación
Monorepos con paquetes locales interdependientes
Pruebas que deben importar el paquete instalado, no la raíz del repositorio

Ejemplo de Trabajo

myapp/
├── pyproject.toml
├── src/
│   └── myapp/
│       ├── __init__.py
│       └── core.py
└── tests/
    └── test_core.py

[project]
name = "myapp"
version = "0.1.0"
requires-python = ">=3.14"
 
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
 
[tool.hatch.build.targets.wheel]
packages = ["src/myapp"]

uv pip install -e ".[dev]"
uv run pytest

# tests/test_core.py
from myapp.core import greet
 
def test_greet():
    assert greet("Ada") == "Hello, Ada!"

Lo que esto demuestra:

El diseño src/ evita importaciones accidentales desde la raíz del repositorio
La instalación editable hace que import myapp resuelva a src/myapp/
Las pruebas ejercitan la misma ruta de importación que usa producción
Los cambios en core.py son visibles en la siguiente ejecución de pruebas sin reinstalar

Profundización

Cómo Funciona

pip install -e . escribe un archivo .pth en el venv apuntando a src/
El backend de compilación descubre paquetes a través de la configuración de pyproject.toml
Las dependencias de ruta (my-utils @ file://...) enlazan paquetes locales al árbol de dependencias
Los espacios de trabajo de uv coordinan múltiples paquetes editables en un monorepo

Diseño `src` vs Diseño Plano

Diseño	Riesgo de importación	Recomendado
`src/myapp/`	Bajo (requiere instalación)	Sí
`myapp/` en la raíz	Las pruebas importan código no instalado	No

Notas de Python

# Espacio de trabajo uv para monorepos
[tool.uv.workspace]
members = ["packages/*"]
 
# packages/myapp/pyproject.toml
[project]
name = "myapp"
dependencies = ["my-utils"]
 
# packages/my-utils/pyproject.toml
[project]
name = "my-utils"

uv sync   # instala todos los miembros del espacio de trabajo de forma editable

Errores Comunes

Las pruebas pasan sin instalación (diseño plano) - CI falla porque el paquete nunca se compiló. Solución: adopta el diseño src/; siempre ejecuta pip install -e . antes de probar.
Instalación editable después de renombrar un paquete - .pth obsoleto apunta a la ruta antigua. Solución: reinstala: uv pip install -e . --force-reinstall.
Dependencias de ruta absoluta en pyproject.toml - falla en otras máquinas. Solución: usa espacios de trabajo uv o dependencias de ruta relativa para monorepos.
Falta __init__.py - los paquetes de namespace pueden confundir el descubrimiento editable. Solución: incluye __init__.py a menos que uses intencionadamente paquetes de namespace.
Publicar un paquete solo editable - pip install desde PyPI necesita una rueda real. Solución: editable es para desarrollo; usa uv build para distribución.

Alternativas

Alternativa	Usar Cuando	No Usar Cuando
`PYTHONPATH=src`	Hack rápido, sin instalación	Producción o CI (frágil)
Instalación regular (`pip install .`)	Verificar el paquete compilado	Desarrollo activo
Espacio de trabajo uv	Monorepo con 2+ paquetes	Aplicaciones de un solo paquete

Preguntas Frecuentes

¿Qué significa -e?

Editable. El paquete instalado enlaza de vuelta a tu directorio de código fuente.

¿Necesito reinstalar después de añadir un nuevo módulo?

No para nuevos archivos .py dentro de un paquete existente. Sí si añades un nuevo paquete de nivel superior o cambias los puntos de entrada.

¿Por qué usar el diseño src/?

Obliga a las pruebas a importar el paquete instalado, detectando errores de empaquetado antes del lanzamiento.

¿Cómo funcionan las dependencias de ruta de monorepo?

Espacios de trabajo uv o dependencies = ["sibling @ file:///${PROJECT_ROOT}/packages/sibling"] con rutas relativas.

¿Puedo instalar una dependencia de forma editable?

Sí: uv pip install -e ../my-utils o declárala como miembro del espacio de trabajo.

¿Editable funciona con Poetry?

Sí: poetry install instala el proyecto actual de forma editable por defecto.

¿Qué pasa con los archivos de datos en modo editable?

Los datos del paquete deben declararse en pyproject.toml ([tool.hatch.build.targets.wheel.force-include]). Las ediciones de código fuente a los archivos de datos se capturan inmediatamente.

¿Cómo verifico la ruta de instalación?

python -c "import myapp; print(myapp.__file__)" debería apuntar a src/myapp/.

¿Editable en Docker?

Monta el código fuente como un volumen e instala pip install -e . en el contenedor para desarrollo con recarga en vivo.

¿Puedo mezclar dependencias editables y regulares?

Sí. Solo tu proyecto (y los hermanos del espacio de trabajo) son editables; las dependencias de PyPI se instalan normalmente.

Relacionado

pyproject.toml Explicado - configuración del paquete
uv - La Cadena de Herramientas Rápida - soporte de espacio de trabajo
Conceptos Básicos de Empaquetado - ruedas y sdists
Mejores Prácticas de Entornos - convenciones de diseño

Versiones de Stack: Esta página fue escrita 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+.

Instalaciones Editables y Paquetes Locales

Buscar en la documentación

Instalaciones Editables y Paquetes Locales