Why is the output of `pip freeze` not a lockfile?

### What `pip freeze` actually does It walks the distributions installed in the current environment, reads each one's recorded name and version, and prints `name==version` lines. That is the whole algorithm. It never consults pyproject.toml, never runs a resolver, and never looks at an index. It reports a **state**, after the fact. ### What a lockfile has to carry A lockfile is the durable output of one resolution, and to be worth the name it needs: * **The resolved graph, with edges.** Which requirement pulled in which package. Without it you cannot drop a dependency and re-resolve, and you cannot audit why something is installed. * **Environment markers.** A single lock that serves Linux, macOS and several interpreter versions has to say *this wheel only when `sys_platform == "linux"`*. Otherwise you need one lock per environment. * **Artefact hashes.** Version numbers name a release; hashes name the bytes. * **Provenance.** The index or URL each artefact came from. * **A link back to the inputs.** The abstract requirements the lock was resolved from, so tooling can tell you the lock is stale when pyproject.toml changes. Frozen output has none of these. It is one column of text. ### The concrete failure modes **Environment pollution.** Freeze reports everything installed, including the debugging tool you pip-installed once at 2am and the leftovers of a package you removed from the project but never uninstalled. Those become permanent deployment dependencies the moment you commit the file. **Direct and transitive are indistinguishable.** Six months later nobody knows which of the sixty lines you actually import. Dropping a dependency becomes guesswork; `pip list --not-required` gives a partial hint by showing distributions nothing else depends on, but it is a heuristic, not a graph. **Platform and interpreter bleed.** Freeze on Linux and you may capture a distribution that only exists for Linux, or a version whose wheel is not published for macOS. Installing the file elsewhere either fails or silently builds from source. Nothing in the file records the environment it was taken from. **Editable and direct-URL installs.** A project installed with `pip install -e .` does not come out as a version pin. It comes out as an `-e` line naming a local filesystem path, which means nothing on another machine or inside a container. `pip freeze --exclude-editable` suppresses those lines -- which is a way of losing the dependency, not of recording it. **No integrity.** Two installs of the same pinned version can differ if the artefact was replaced on an index or a mirror. Only hashes catch that. ### The ladder from freeze to a lockfile 1. **`pip freeze`** -- a snapshot. Fine for reporting what is in a container you are debugging; not an input you should build releases from. 2. **A compiled requirements file** (for example `pip-compile` output) -- a real resolution of your abstract requirements, pinned, annotated with which requirement pulled each package, and optionally generated with hashes for `--require-hashes`. Still typically one file per platform, because a plain requirements file expresses markers awkwardly. 3. **A tool-owned lockfile** -- `uv.lock` or `poetry.lock`. Multi-platform through markers, hash-verified, tied to the abstract inputs, and regenerated rather than edited. The cost is that the format belongs to one tool. 4. **`pylock.toml`** -- the standardised, tool-neutral lock format defined by PEP 751, which packaging tools are progressively adopting as an interchange and export target. ### How to answer the practical version of this question If someone hands you a `pip freeze` output and calls it a lockfile, the fix is not to reformat it. Write the abstract requirements down in pyproject.toml, resolve them with a tool that produces a real lock, and treat the pinned artefact as generated: regenerate on upgrade, review the diff, and let CI install from it rather than resolve afresh on every run.