Editable Installs

### Both commands go through the build backend `pip install .` and `pip install -e .` begin identically. pip reads `pyproject.toml`, looks at the `[build-system]` table, installs the declared build backend into an isolated build environment, and calls it. What differs is *which hook* pip asks for, and therefore what the resulting wheel contains. For a plain install pip asks the backend to build a normal wheel. A wheel is a zip file holding the importable package's `.py` files, any package data, and a `.dist-info` metadata directory. pip unpacks that into the environment's `site-packages`. From that moment the environment owns a private copy of your code, and the interpreter never looks at your source tree again — it looks at `site-packages`. That is exactly what a user gets when they install your project from an index, which is the value of a plain install: it exercises the real artefact. For an editable install pip asks the backend for an *editable* wheel, the hook standardised by PEP 660. The backend is free to decide how that wheel redirects imports, and the two common shapes are both tiny. The simplest writes a `.pth` file into `site-packages` whose single line is the absolute path of the directory containing your importable package; the `site` module reads every `.pth` in `site-packages` at interpreter start and appends such lines to `sys.path`, so `import yourpkg` resolves into your working tree. The stricter shape writes a `.pth` line that imports a generated module which registers a finder on `sys.meta_path`, mapping only the package names the project actually declares to their files on disk. Either way, the module source is never copied into the environment. ### An editable install is still an install This is the part candidates most often get wrong. An editable install is not a hack outside the packaging system. pip writes a normal `.dist-info` directory with `METADATA` and `RECORD`; the distribution appears in `pip list` and can be uninstalled; its declared dependencies are resolved and installed exactly as for any other install; another distribution that requires it is satisfied; `importlib.metadata.version("your-dist-name")` returns its version; and any console scripts it declares are generated into the environment's script directory. Because the install came from a local path, pip also records a `direct_url.json` in the `.dist-info` whose `dir_info` object carries `"editable": true`, which is how tooling can tell an editable install apart after the fact. ### The distribution and the importable package are different names Worth keeping straight while answering. The *distribution* is what pip installs and what `pip list` shows — the `name` in `[project]`. The *importable package* is the directory with `__init__.py` that `import` finds. They routinely differ in spelling, and an editable install is precisely the link between them: it teaches the environment that this distribution's importable package lives over there in your checkout. ### What "no reinstall needed" does not cover Only the module source is redirected. Metadata is snapshotted when you install, so adding a dependency, bumping the version, or declaring a new console script all need the install re-run. A compiled extension module still has to be rebuilt — editing its C source changes nothing until it is compiled. And a *running* interpreter caches imported modules in `sys.modules`; your edit is picked up by the next process, not by the one already executing. Development servers create the illusion of live editing by restarting the process for you. ### When to use which Use `-e` in a development environment and while running the test suite locally, where the whole point is a fast edit-run loop and where you want the tests to import the code the same way a user would. Use a built wheel everywhere the artefact matters: in a container image, in the packaging job of a pipeline, and in production. An editable install ties the environment to a working tree that may be dirty, may move, or may not exist on the target machine, and it hides a classic packaging bug — a module that imports fine because the whole source directory is on `sys.path`, but was never declared and so is missing from the real wheel. Building the wheel once and installing it is what surfaces that before a user does.