Model and data securityMiddleLesson 1725 min read

Model files that run code: pickle and safetensors

Some model file formats can run code the moment you load them. Learn why, and how to load models safely.

✦ Ask the tutor🧪 Lab · 20 min📝 Lesson test
Lesson in motion

In 60 seconds

Model files that run code: pickle and safetensors

Some model file formats can run code the moment you load them. Learn why, and how to load models safely.

1/5
In simple words
Some parcels are just boxes with things inside. Others are like a box with a spring that jumps out when you open the lid. A pickle model file can be the second kind: opening it can make things happen on your computer.
Python's pickle format saves Python objects so they can be loaded later. To rebuild some objects, pickle can call functions while loading. That means a pickle file can be written to run any code when it is loaded. The Python documentation itself warns never to unpickle data from an untrusted source.
Many machine learning tools have used pickle, directly or inside other formats, to save models. So downloading a model file and loading it can be the same as running a program from a stranger.

Safer formats

FormatCan run code on load?Notes
Python pickle (and formats built on it)YesOnly load from sources you fully trust
safetensorsNo, it stores tensors onlyDesigned to be safe and fast to load; widely supported
ONNXNot designed to run arbitrary Python on loadStill check custom operators and the runtime you use
GGUF and similar weight formatsNot designed to run arbitrary code on loadLoader bugs are still possible; keep tools updated
safetensors stores only named arrays of numbers (tensors) and a small header. Loading it reads data; it does not rebuild arbitrary Python objects. Prefer it whenever you share or download weights.
Load weights from safetensors after checking the hashpython
import hashlib
from safetensors.torch import load_file

EXPECTED_SHA256 = "paste-the-published-hash-here"
path = "model.safetensors"

h = hashlib.sha256()
with open(path, "rb") as f:
    for chunk in iter(lambda: f.read(1 << 20), b""):
        h.update(chunk)

if h.hexdigest() != EXPECTED_SHA256:
    raise SystemExit("Hash mismatch: do not load this file")

state_dict = load_file(path)          # reads tensors only
print(len(state_dict), "tensors loaded")
# model.load_state_dict(state_dict)   # into a model class you trust

Other ways model loading runs code

  • Some libraries have an option, often named like trust_remote_code, that downloads and runs Python code shipped with a model repository. Turning it on means running that author's code on your machine.
  • Custom layers or operators may need extra code you install.
  • Notebooks, setup scripts and example code in a model repository are ordinary code too.
  • Some frameworks offer safer loading modes, such as PyTorch's weights_only option for torch.load. Check what your version supports and make it the default.

A safe loading policy

  1. 1

    Prefer safe formats

    Ask for or convert to safetensors. Refuse pickle from unknown sources.
  2. 2

    Verify

    Check the hash (and signature, where available) against what the publisher states.
  3. 3

    Scan

    Run a model scanner that looks for dangerous code in pickle-based files. Scanners help but can miss things.
  4. 4

    Isolate

    Load any untrusted model in a sandbox: a throwaway container or VM with no secrets, no cloud credentials and no network.
  5. 5

    Review remote code

    If remote code is truly needed, read it, pin the exact revision, and store a reviewed copy.
Danger
Never load an untrusted pickle-based model on a laptop or server that holds cloud keys, SSH keys or production access. If it runs code, it runs with your permissions.
Try this. Search your code for pickle.load, torch.load, joblib.load and remote-code options. For each, write down where the file comes from.

Watch and read more

pickle — Python object serialization (see the warning)Python documentation · reading

Lab

A script that verifies a model file's hash and loads it with safetensors, plus an inventory of risky loads in your code.

~20 min

The problem

Download a small, well-known open model that is published in safetensors format, from its official page, along with its published hash (many hubs show the SHA-256 of each file).

  1. Adapt the lesson's code sample: compute the SHA-256 and compare it with the published value.
  2. Change one byte of a copy of the file and show the script refuses it.
  3. Load the original with safetensors and print the tensor names and shapes.
  4. Search one of your own repositories for pickle.load, torch.load, joblib.load and remote-code options. List each with the file's source.

Do not write or run any pickle file designed to execute code.

You are done when

Hard questions

Try to answer before you reveal. If you can answer these, you understood the lesson.

Q1A hash matches the one on the model page. What does that prove, and what does it not prove?Reveal

It proves the file you have is the same as the one the page describes, so it was not corrupted or swapped on the way. It does not prove the file is safe or that the publisher is trustworthy. If an attacker controls the page, they can publish a bad file with a matching hash. Signatures tied to a known identity, and trust in the source, cover that gap.

Q2Why is a sandbox without network access important even if the model file is safetensors?Reveal

The weights may be safe, but other parts might not be: remote code, custom operators, tokenizer files, or bugs in the loader. Without network access, any code that does run cannot send data out or download more tools. It is cheap insurance.

Please sign in to continue.

Questions people ask

Is every pickle file dangerous?

A pickle file you created yourself and stored safely is fine to load. The danger is loading one that someone else could have made or changed. The format cannot tell you which it is.

Can we convert an untrusted pickle model to safetensors safely?

Converting usually means loading the pickle first, which is the risky step. Do it only inside an isolated sandbox with no secrets and no network, then verify and use the safetensors output.

Do model hubs scan uploads?

Some platforms scan uploaded files and show warnings. This is helpful, but do not rely on it alone. Scanners can miss new tricks, and files can come from many other places, such as shared drives and chat attachments.

What about scikit-learn models saved with joblib?

joblib uses pickle underneath, so the same rules apply. Load only files you trust, or use a format meant for safe exchange where your tools support it.

Lesson test

5 questions. Get 3 right (60%) to pass and complete this lesson.

Sign in to take the test and save your progress