pip --require-hashes: pin the Python dependencies of a self-hosted AI server
TL;DR: A self-hosted AI server is mostly Python packages you did not write, and pip install -r requirements.txt with loose version ranges installs whatever the index serves today. The fix that costs two commands is a hash-locked requirements file: pip-compile --generate-hashes writes every package, every transitive dependency and every allowed file hash, and pip install --require-hashes -r requirements.txt refuses anything that does not match. I reproduced this today on pip 25.1.1 and pip-tools 7.7.0 with a five-package tree (requests plus its four dependencies, 180 --hash lines). The part that is worth knowing in advance is how it fails: four different mistakes produce only two different error messages, and the one for an edited hash prints the expected and the actual SHA-256 side by side. Another surprise: a single --hash anywhere in a requirements file switches hash checking on for the whole install, even without the flag.
What you’ll be able to do:
- Generate a hash-locked
requirements.txtfrom a shortrequirements.inand install from it. - Read the two
--require-hasheserrors and know which of four mistakes each one means. - Add a hash for one downloaded wheel with
pip hash, and understand why that one line can break an install. - Decide which parts of a self-hosted AI stack this protects, and which parts it does not.
Honest take: I tested the mechanism with
requests, not with an AI framework, so the package names below are a stand-in for whatever your server uses. Everything here ran on one Linux machine with Python 3.13.5 in a fresh virtual environment, using the public PyPI index. A hash lock tells you the files are the same ones you recorded. It does not tell you those files are safe, and it does not stop you from locking a bad version in the first place.
What a hash lock actually protects
An unlocked install has three moving parts. The top-level package version can change (requests without a pin). Its dependencies can change (a urllib3 range such as <3,>=1.21.1 resolves to whatever is newest in the range). And the file that comes back for a given name and version can change, if the index, a mirror in front of it, or a proxy returns something different.
Pinning versions with == fixes the first two only if you pin every transitive dependency too, which no one does by hand. Hashes fix the third. The pip documentation describes hash-checking mode as using “local hashes, embedded in a requirements.txt file, to protect against remote tampering and network issues.” It is meant for the situation where you have already decided which files you trust, and the install step should reproduce that decision exactly.
For a self-hosted AI server this matters because the install step often runs somewhere unattended: a Dockerfile build, a systemd unit’s pre-start script, an ansible task. The LiteLLM CVE patch guide, the Langflow hardening guide and the open-source AI vulnerability overview on this site cover specific problems in packages that people run exactly this way. A hash lock does not patch any of them. It makes “which version is running” a fact you can read from a file instead of a guess.
Step 1: write the short file, compile the long one
The input file is one line. I used requests as the example package:
$ cat req.in
requests==2.32.3
pip-compile comes from the pip-tools package. I installed pip-tools 7.7.0 into a fresh virtual environment and compiled:
$ pip-compile --generate-hashes --no-emit-trusted-host --strip-extras --index-url https://pypi.org/simple -o requirements.txt req.in
Two flags are worth a note. --no-emit-trusted-host stops pip-tools from writing a --trusted-host line for a mirror you may have configured globally; on this server the default index was a Tencent Cloud mirror, and without the flag its host name ended up in the output file. --strip-extras silences a warning that the default changes in pip-tools 8.0.0.
The result is a 196-line file containing five pinned packages and 180 hash lines:
$ grep -E '^[a-z]' requirements.txt
certifi==2026.11.20 \
charset-normalizer==3.5.2 \
idna==3.20 \
requests==2.32.3 \
urllib3==2.8.0 \
$ grep -c '^ --hash' requirements.txt
180
One input line became five pins, and each pin carries one hash for every file PyPI lists for that version. Four of the five have 2 hashes (a wheel and a source archive). charset-normalizer has 172 of the 180, because it ships a separate compiled wheel per Python version and platform (I counted them with a short script). That is why the file is long. You are saying “any of these exact files is acceptable”, not “this one file”.
Each block names the package that pulled it in, as a comment:
certifi==2026.11.20 \
--hash=sha256:7422df25243767b9877031a2248cb14d09ddac9beee846f4cef3d5c9191d488f \
--hash=sha256:af1cb240a8133f105aa52684a3a3258339d7f2fd0bd4e2812698ff5cf5588c4e
# via requests
Step 2: install with the flag
In a clean virtual environment:
$ pip install --require-hashes -r requirements.txt
Collecting requests==2.32.3 (from -r requirements.txt (line 189))
Downloading requests-2.32.3-py3-none-any.whl (64 kB)
Collecting urllib3==2.8.0 (from -r requirements.txt (line 193))
Using cached urllib3-2.8.0-py3-none-any.whl (135 kB)
Installing collected packages: urllib3, idna, charset-normalizer, certifi, requests
Successfully installed certifi-2026.11.20 charset-normalizer-3.5.2 idna-3.20 requests-2.32.3 urllib3-2.8.0
(The output above is trimmed to the lines that matter.) Five packages at the exact versions in the file. The next four sections are the ways that command fails, because those messages are what you will meet at 2 a.m. when a Docker build goes red.
Failure 1: a hash does not match
I changed the first character of both certifi hashes and ran the install again, with --no-cache-dir so pip had to download the file instead of reusing a cached copy:
$ pip install --no-cache-dir --require-hashes -r tampered.txt
Collecting certifi==2026.11.20 (from -r tampered.txt (line 7))
Downloading certifi-2026.11.20-py3-none-any.whl (127 kB)
ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE. If you have updated the package versions, please update the hashes. Otherwise, examine the package contents carefully; someone may have tampered with them.
certifi==2026.11.20 from https://files.pythonhosted.org/packages/6d/39/5eec3296860b94ac20bb8ed807725b88f6adfab3f343df592afd975f5f86/certifi-2026.11.20-py3-none-any.whl (from -r tampered.txt (line 7)):
Expected sha256 8422df25243767b9877031a2248cb14d09ddac9beee846f4cef3d5c9191d488f
Expected or bf1cb240a8133f105aa52684a3a3258339d7f2fd0bd4e2812698ff5cf5588c4e
Got 7422df25243767b9877031a2248cb14d09ddac9beee846f4cef3d5c9191d488f
This message is the useful one. It shows the file’s URL, every hash you allowed, and the hash of the file pip actually received. The Got value, 7422df25…, is the original, correct hash from the unmodified file, which is how I know the break was in my edit and not in the download. In a real incident you read this message in the other direction: the expected values are the ones you locked, the Got value is what arrived. If you only changed a version in requirements.in and forgot to recompile, the fix is to recompile. If you did not touch anything, the message’s own advice applies: look at what was served before you do anything else.
Failure 2: the requirement is not pinned
$ cat unpinned.txt
requests
$ pip install --require-hashes -r unpinned.txt
Collecting requests (from -r unpinned.txt (line 1))
ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. These do not:
requests from https://files.pythonhosted.org/packages/a0/f4/c67b0b3f1b9245e8d266f0f112c500d50e5b4e83cb6f3b71b6528104182a/requests-2.34.2-py3-none-any.whl (from -r unpinned.txt (line 1))
Look at the URL in the message. At the moment I ran this, an unpinned requests would have resolved to requests-2.34.2, not the 2.32.3 in my lock. That is a concrete picture of what the unlocked install does: it moves. Hash mode refuses to guess.
Failure 3: a dependency is missing from the file
This is the one that bites people who edit a lock file by hand. I deleted the urllib3 block (five hash lines) from the compiled file and left everything else alone. grep -c '^urllib3' printed 0, then:
$ pip install --require-hashes -r missing.txt
Collecting requests==2.32.3 (from -r missing.txt (line 189))
Using cached requests-2.32.3-py3-none-any.whl (64 kB)
Collecting urllib3<3,>=1.21.1 (from requests==2.32.3->-r missing.txt (line 189))
ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. These do not:
urllib3<3,>=1.21.1 from https://files.pythonhosted.org/packages/92/9d/c4e665119135114480843e7ab388fa94d8480650450e6f8e26b70d323a4c/urllib3-2.8.0-py3-none-any.whl (from requests==2.32.3->-r missing.txt (line 189))
The wording is the same as Failure 2, which is misleading: nothing in your file is unpinned. requests itself asked for urllib3<3,>=1.21.1, that range is not in the file, and hash mode will not resolve it for you. The way to read the error is to find the from requests==2.32.3-> part, which names the package that wanted the dependency. The fix is always to recompile, never to add the line by hand.
Failure 4: one hash switches the whole install into hash mode
The pip documentation says: “hash-checking is an all-or-nothing proposition. Specifying —hash against any requirement will activate this mode globally.” I wanted to see that for myself, because it explains how a half-edited requirements file breaks a build that did not pass --require-hashes.
First, pip hash computes the SHA-256 of a file you already downloaded, in the format the requirements file wants:
$ pip download -q --no-deps -d dl requests==2.32.3
$ pip hash dl/requests-2.32.3-py3-none-any.whl
dl/requests-2.32.3-py3-none-any.whl:
--hash=sha256:70761cfe03c773ceb22aa2f671b4757976145175cdfca038c02654d061d6dcc6
I put that hash on one line and nothing else, with no --require-hashes on the command line:
$ cat partial.txt
requests==2.32.3 --hash=sha256:70761cfe03c773ceb22aa2f671b4757976145175cdfca038c02654d061d6dcc6
Installed with --no-deps, that works: the one package has its hash, and pip does not look at dependencies. Installed without --no-deps, it fails the moment pip has to resolve a dependency:
$ pip install -r partial.txt
Requirement already satisfied: requests==2.32.3 in ./t2/lib/python3.13/site-packages (from -r partial.txt (line 1)) (2.32.3)
Collecting charset-normalizer<4,>=2 (from requests==2.32.3->-r partial.txt (line 1))
ERROR: In --require-hashes mode, all requirements must have their versions pinned with ==. These do not:
charset-normalizer<4,>=2 from https://files.pythonhosted.org/packages/4b/85/41d27f234b82e47c167a5f6c0f62501dc0c640585ff4aba79e08a390336a/charset_normalizer-3.5.2-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl (from requests==2.32.3->-r partial.txt (line 1))
The error says --require-hashes mode even though I never passed the flag. One --hash was enough. If a teammate pastes a single hashed line into an otherwise loose requirements file, the next build breaks with a message about “pinned versions” that does not mention hashes at all. Now you know the cause.
| What you did | What pip said | Real meaning |
|---|---|---|
| Edited or corrupted a hash | THESE PACKAGES DO NOT MATCH THE HASHES with Expected and Got | The downloaded file differs from the locked one |
| Left a package unpinned | all requirements must have their versions pinned with == | Your file has a bare name |
| Removed a block from a compiled file | the same pinned-with-== message | A package’s dependency range is no longer covered |
Added one --hash to a loose file | the same pinned-with-== message, in --require-hashes mode | Hash mode is on for the whole install |
What this does not cover
- A vulnerable version, locked. If the version you pinned has a CVE, the hash lock will reproduce it faithfully. Recompile on a schedule, and when an advisory lands for something in the tree.
- Source distributions. The pip documentation also mentions
--only-binary :all:to disallow source distributions, since building one runs the package’s build scripts. I did not test that flag in this reproduction. - Everything that is not Python. Model weights, system packages, container base images and npm packages are separate trust decisions. For model files, see the checks in GGUF header checks and safetensors header checks.
- Index choice. Hashes protect the contents of the file, not the decision of which index you asked. Keep
--index-urlexplicit in your build, as in the command above.
I only tested a single resolver run with one top-level package on one Python version. Platform-specific wheels are included in the hash list, but I did not install the lock on a second platform, so I make no claim about that case here.
Wiring it into a build
Keep requirements.in in Git as the file a person edits, and requirements.txt as the generated lock. A build or a systemd pre-start step runs one line:
pip install --require-hashes --no-deps -r requirements.txt
--no-deps is deliberate here. Every dependency is already in the file, with its own hash, so asking pip to resolve anything is a sign the lock is incomplete; with --no-deps pip installs only what the file lists. I ran exactly this command against the full 180-hash file in a fresh virtual environment and it exited 0 with the same five packages and versions as Step 2. Run a throwaway build with your own lock before you rely on it in production.
To update, edit requirements.in, rerun the pip-compile command, and read the diff of requirements.txt like any other code change: new packages, version bumps and new hashes are all visible there.
Honest take
A hash lock is one of the cheapest controls available for a Python AI service: two commands to create, one flag to enforce, and error messages that say what happened once you know how to read them. The sharp edge is the mismatch between what pip says and what you did: “all requirements must have their versions pinned with ==” covers three different mistakes. If you take one thing from this article, take the table above.
It will not make a service secure. It makes your install repeatable and your supply-chain decisions reviewable, which is the precondition for everything else.
Sources
- Secure installs — Hash-checking Mode (
--require-hashes, “all-or-nothing”,--only-binary :all:) — pip documentation - pip hash — compute the SHA-256 of a downloaded file — pip documentation
- pip install —
--require-hashes,--no-deps,--no-cache-dir— pip documentation - pip-tools —
pip-compile --generate-hashes,--strip-extras,--no-emit-trusted-host— GitHub - requests 2.32.3 release files on PyPI — the Python Package Index
- Requirements File Format —
--hashoption per requirement — pip documentation - Reproduction output: pip 25.1.1, pip-tools 7.7.0, Python 3.13.5 on Linux, November 21, 2026 —
pip-compile --generate-hashes,pip install --require-hashes, a deliberately edited hash, an unpinned requirement, a deleted dependency block,pip hash, and a single-hash requirements file
Last updated November 21, 2026. The package versions and URLs in the output above are what PyPI served on November 21, 2026 and will change; recompile your own lock instead of copying these pins. Every command output was produced in a throwaway virtual environment on Linux with pip 25.1.1 and pip-tools 7.7.0.
Was this article helpful?
Thanks for the feedback — it helps improve future articles.
Need hands-on help?
I offer 1-on-1 technical consulting for local AI setup, GPU selection, and AI coding tool configuration — same topics covered on this site.
Book a session — $49 / hour →What self-hosting actually costs
Real cost breakdowns for self-hosted AI: hardware floors, power, maintenance hours, and the honest comparison against paying for it. No spam, unsubscribe anytime.