Python's pickle documentation opens with a warning: the module is not secure, only unpickle data you trust, and malicious pickle data can run arbitrary code during unpickling. The same page points to HMAC signing, JSON, restricted globals and pickletools. Read those five pointers, because many model files are pickles under another name.
1. The warning is the first thing on the page
The page says the pickle module is not secure, tells you to only unpickle data you trust, and says never to unpickle data that could have come from an untrusted source or been tampered with. For an ML engineer, "data" includes a model checkpoint. A downloaded weights file in a pickle based format falls squarely under this sentence.
2. HMAC is suggested for integrity
The warning continues: consider signing data with hmac if you need to ensure it has not been tampered with. That is a tool for internal handoffs, where two systems share a secret key. It proves the bytes came from someone holding the key and were not changed. It says nothing about whether the producer was trustworthy. See can you sign pickle files with HMAC for internal model handoffs.
3. JSON is the documented alternative for untrusted data
The page says safer formats such as json may be more appropriate for untrusted data. Its comparison section adds that, unlike pickle, deserializing untrusted JSON does not in itself create an arbitrary code execution vulnerability. The tradeoff is range: JSON represents only a subset of built in types and no custom classes.
For metadata, config and small tables, JSON usually does the job. For large tensors you need a binary format, which is where safetensors comes in. See safetensors versus pickle versus GGUF.
4. Unpickling imports whatever the file asks for
Under Restricting Globals, the page explains that by default unpickling imports any class or function named in the data. It shows a hand made stream that imports os.system and applies it to a string. It then describes customizing find_class, which is called whenever a global is requested, to forbid globals or limit them to a safe subset.
This is the mechanism behind every allowlist approach to pickle. It also shows the limit: the allowlist is only as good as the names on it. For a deeper look see how a restricted unpickler blocks malicious model files.
5. pickletools reads without running
The page says the pickletools module contains tools for analyzing data streams generated by pickle. Hugging Face's guide uses its genops function to list imports in a pickle without executing it. This is the safe way to look inside an unknown file, on an isolated machine.
Turning the five points into rules
| Documentation point | Team rule |
|---|---|
| Only unpickle trusted data | No pickle based files from outside the team on machines with real credentials |
| Sign with HMAC | Sign internal handoffs and verify before load |
| JSON for untrusted data | Use JSON for config and metadata crossing trust boundaries |
| Restrict globals | If you must load pickles, use an allowlist and own it |
| pickletools | Inspect with a disassembler before first load |
Quick check
Does HMAC make a pickle safe to load?
It shows the file was not altered and came from a key holder. It does not show the producer is trustworthy.
Can I read a pickle without running it?
Yes. The pickletools module can disassemble the stream without executing it.
Safeguard's dependency scanning and policy gates cover the packages in the project that loads these files. Try the free scan.
Sources
Last reviewed: 19 October 2026.
