Para instalar un proyecto local de Python en modo editable en macOS, abra Terminal, vaya al directorio del proyecto, cree y active un entorno virtual y luego ejecute python -m pip install -e .. Esto vincula las importaciones de Python a su árbol de código fuente de trabajo, de modo que los cambios en los archivos de Python están disponibles en nuevas sesiones del intérprete sin necesidad de reinstalar. El proyecto todavía necesita metadatos de empaquetado, y el comportamiento editable exacto depende de su backend de compilación.

Qué hace una instalación editable

Una instalación regular coloca el proyecto en el entorno de Python seleccionado como un paquete instalado. En cambio, una instalación editable hace que el código fuente en el directorio de desarrollo esté disponible en la ruta de importación de Python. Es útil cuando está modificando ese proyecto localmente; no significa que todos los archivos del proyecto o recursos que no sean de Python se gestionen automáticamente de la misma manera. Guía de instalación de proyectos locales de pip

El modo editable tampoco hace que los cambios en las dependencias desaparezcan. pip instala las dependencias declaradas por el proyecto de la forma habitual, a menos que use --no-deps. Los cambios en el código fuente de Python generalmente son visibles en la siguiente ejecución, pero un cambio en los metadatos del proyecto, los scripts generados de línea de comandos o el código compilado puede requerir una reinstalación o una recompilación. Guía del usuario de empaquetado de Python: Empaquetado y distribución de proyectos

Preparar un entorno virtual en macOS

En Terminal, cambie a la carpeta raíz del proyecto, el directorio que contiene pyproject.toml o un archivo heredado compatible setup.py. El siguiente comando cd asume que la carpeta está en su directorio de inicio; entrecomille la ruta si contiene espacios.

cd "$HOME/path/to/my-project"
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip --version

El entorno virtual mantiene los paquetes instalados de este proyecto separados de otros entornos de Python. Tras la activación, python debería referirse al intérprete del entorno, por lo que el uso de python -m pip vincula pip a ese intérprete. La documentación de Python describe venv como una herramienta para crear entornos aislados y documenta el comando de activación para shells POSIX, incluido el shell utilizado por defecto en las configuraciones actuales de Terminal en macOS. Documentación de Python: venv

Si no se encuentra python3, instale o localice primero un intérprete de Python 3; macOS no garantiza que haya un Python listo para el desarrollo disponible bajo ese comando. Si el proyecto especifica una versión de Python compatible, use esa versión para crear .venv. Evite instalar paquetes en un Python administrado por el sistema cuando un entorno de proyecto sea suficiente.

Instalar el proyecto en modo editable

Con el entorno activo y la Terminal aún en la raíz del proyecto, ejecute:

python -m pip install -e .

Aquí, -e significa editable y . representa el directorio actual. pip espera que el directorio de un proyecto local contenga pyproject.toml o setup.py. Los proyectos modernos suelen declarar un backend de compilación en pyproject.toml; pip solicita a ese backend que realice la instalación editable. El backend debe admitir la interfaz de instalación editable para que esto funcione según lo previsto. Referencia de pip install, Interfaz del sistema de compilación de pip

Para instalar desde un directorio diferente, proporcione su ruta en lugar de ., por ejemplo python -m pip install -e "$HOME/path/to/my-project". Entrecomillar la ruta protege los espacios y los metacaracteres del shell. La instalación se aplica al entorno de Python asociado con el comando python que utilizó.

Confirmar el entorno y diagnosticar errores

Consulte la vista de proyectos instalados de pip para confirmar que enumera el paquete y la ubicación de su proyecto editable:

python -m pip list

Luego inicie Python desde el entorno activado e intente importar el paquete utilizando su nombre de importación documentado. El nombre de importación puede diferir del nombre de distribución del proyecto, por lo que debe consultar el archivo README o el directorio del paquete del proyecto en lugar de adivinarlo. Si la importación solo funciona desde una carpeta, compruebe que la instalación apunte a la raíz prevista del proyecto y que el paquete esté configurado para ser detectado por su backend.

Si pip indica que el directorio no se puede instalar, verifique que se encuentra en la raíz correcta y que contiene pyproject.toml o setup.py. Si el backend de compilación rechaza el modo editable, actualice o configure el backend del proyecto de acuerdo con su documentación; no todos los backends antiguos o personalizados admiten instalaciones editables. Para un proyecto moderno con pyproject.toml, pip utiliza el hook editable PEP 660 del backend. Interfaz del sistema de compilación de pip

Si un cambio en el proyecto añade dependencias, puntos de entrada o modifica metadatos, vuelva a ejecutar python -m pip install -e .. En el caso de extensiones compiladas, ejecute también los pasos de compilación documentados del proyecto. pip advierte que las instalaciones editables y las regulares pueden comportarse de manera diferente, por lo que una instalación editable está pensada para el desarrollo local; no reemplaza la verificación de la ruta de instalación ordinaria antes de distribuir un paquete. Guía de instalación de proyectos locales de pip

Fuentes