To install a local Python project in editable mode on macOS, open Terminal, move to the project directory, create and activate a virtual environment, then run python -m pip install -e .. This links Python imports to your working source tree, so changes to Python files are available in new interpreter sessions without reinstalling. The project still needs packaging metadata, and the exact editable behavior depends on its build backend.

What an editable install does

A regular install places the project into the selected Python environment as an installed package. An editable install instead makes the source in the development directory available on Python’s import path. It is useful when you are changing that project locally; it does not mean every project file or non-Python resource is automatically handled the same way. pip’s local project install guide

Editable mode also does not make dependency changes disappear. pip installs dependencies declared by the project in the usual way, unless you pass --no-deps. Changes to Python source code are generally visible on the next run, but a change to project metadata, generated command-line scripts, or compiled code can require reinstalling or rebuilding. Python Packaging User Guide: Packaging and distributing projects

Prepare a virtual environment on macOS

In Terminal, change to the project’s root folder, the directory containing pyproject.toml or a supported legacy setup.py. The cd command below assumes the folder is in your home directory; quote the path if it contains spaces.

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

The virtual environment keeps this project’s installed packages separate from other Python environments. After activation, python should refer to the environment’s interpreter, so using python -m pip ties pip to that interpreter. Python’s documentation describes venv as creating isolated environments and documents the activation command for POSIX shells, including the shell used by default in current macOS Terminal setups. Python documentation: venv

If python3 is not found, install or locate a Python 3 interpreter first; macOS does not guarantee that a development-ready Python is available under that command. If the project specifies a supported Python version, use that version to create .venv. Avoid installing packages into a system-managed Python when a project environment will do.

Install the project in editable mode

With the environment active and Terminal still at the project root, run:

python -m pip install -e .

Here, -e means editable and . means the current directory. pip expects a local project directory to contain pyproject.toml or setup.py. Modern projects typically declare a build backend in pyproject.toml; pip asks that backend to perform the editable installation. The backend must support the editable-install interface for this to work as intended. pip install reference, pip build system interface

To install from a different directory, provide its path instead of ., for example python -m pip install -e "$HOME/path/to/my-project". Quoting the path protects spaces and shell metacharacters. The install applies to the Python environment associated with the python command you used.

Confirm the environment and diagnose errors

Check pip’s installed-project view to confirm that it lists the package and its editable project location:

python -m pip list

Then start Python from the activated environment and try importing the package using its documented import name. The import name can differ from the project’s distribution name, so consult the project’s README or package directory rather than guessing. If the import works only from one folder, check that the install points to the intended project root and that the package is configured for discovery by its backend.

If pip says the directory is not installable, verify that you are in the correct root and that it contains pyproject.toml or setup.py. If the build backend rejects editable mode, update or configure the project’s backend according to its documentation; not every older or custom backend supports editable installs. For a modern pyproject.toml project, pip uses the backend’s PEP 660 editable hook. pip build system interface

If a project change adds dependencies, entry points, or changes metadata, rerun python -m pip install -e .. For compiled extensions, run the project’s documented build steps as well. pip notes that editable and regular installs can behave differently, so an editable install is for local development; it does not replace checking the ordinary installation path before distributing a package. pip’s local project install guide

Sources