What does pip install --target do, and how do those packages end up on sys.path?

## What the flag actually does A normal `pip install` resolves a dependency set, downloads or builds wheels, and unpacks them into the `site-packages` directory of whatever environment pip belongs to, registering each one with a `.dist-info` directory. `--target DIR` changes only the destination: the same resolution and the same unpacking happen, but the results land in `DIR`. What you get afterwards is an ordinary directory holding importable top-level packages and modules beside their `.dist-info` metadata — nothing else. Console-script wrappers land inside the target tree rather than anywhere on `PATH`, and there is no `pyvenv.cfg`, no `activate`, and nothing for pip to later uninstall from. ## Why nothing imports until you say so This is the part candidates get wrong. A virtual environment gets onto `sys.path` because the interpreter starting from that environment computes its own `site-packages` and the `site` module adds it. A `--target` directory participates in none of that. It becomes importable only if something puts it on the path: ```console python -m pip install --target ./vendor -r requirements.txt PYTHONPATH=./vendor python -m myapp ``` or by inserting it from inside the program before the first third-party import, or implicitly because the directory *is* `sys.path[0]` — which is exactly what happens when the vendored tree sits at the root of a zipapp archive next to `__main__.py`, or when the process's working directory is the vendor tree. Because the entry lands at the front when you insert it yourself, a vendored package can shadow a same-named module installed on the host, which is sometimes the point and sometimes a subtle bug. ## Where it is the right tool `--target` exists for delivery shapes that have no interpreter environment to install into. Building a single-file archive is one: the dependencies have to be *files in a directory* before they can be zipped. Function-style deploy targets that expect a flat directory of code plus libraries are another. So is a constrained appliance where you copy a tree into place and cannot run a package manager at deploy time. In all of those the pattern is the same: resolve once on a build machine, produce a directory, ship the directory, and let the runtime find it. What it is *not* is a lightweight virtual environment. If the target can create an environment, `python -m venv` plus an install into it is better in every way that matters — pip can then upgrade and uninstall coherently, the environment records its base interpreter, and console scripts work. ## The failure modes **Drift.** Because pip is not managing the directory, running `--target` into a non-empty tree overwrites the files it installs this time and silently leaves behind everything from previous runs, including packages you removed from the requirements and older top-level modules of packages that reorganised. The result is a tree that imports something no lockfile mentions. The discipline is: the vendor directory is a build output, deleted and rebuilt from empty on every build, never patched in place. **Platform.** pip resolves for the interpreter running it. Vendoring on a developer laptop and shipping to a different operating system or CPU gives you wheels that will not import. For a build that must target another platform, pip accepts `--platform`, `--abi` and `--python-version`, but only when the destination is a `--target` directory and the resolution is binary-only (`--only-binary=:all:`, or `--no-deps`), because it cannot run arbitrary builds for a platform it is not on: ```console python -m pip install --target ./vendor \ --platform manylinux_2_28_x86_64 --only-binary=:all: -r requirements.txt ``` Any dependency without a wheel for that tag fails the command outright — which is the useful behaviour, because the alternative is discovering it on the deploy host. **Compiled dependencies plus a zip.** A vendored tree that contains a binary extension module is fine as a directory but cannot be imported from inside a zip archive, so `--target` output destined for a zipapp must be pure Python. **Metadata still works, if you keep it.** `importlib.metadata` reads the `.dist-info` directories, so version lookups and entry-point discovery keep working against a vendored tree as long as the path is on `sys.path` and the `.dist-info` directories were not stripped to save space. Stripping them is a classic self-inflicted wound: the application starts, then fails much later when some library asks for its own version. ## The interview shape of the answer Say what it does (installs into a plain directory), say what it does not do (put that directory on `sys.path`, manage the directory over time, adapt to the target's platform for you), and name the shapes it serves. The strongest version of the answer ends by saying when you would *not* use it: if the target can hold a virtual environment or an image, vendoring by hand is a step backwards.