Safetensors

Safetensors saves a model’s weights as raw numbers plus a JSON description, in a format that, its README says, cannot save custom code.

How it works

A safetensors file has three parts. The first 8 bytes give the size of the header. The header is JSON that lists each tensor by name, with its data type, shape and where its bytes sit. The rest of the file is those bytes. The README allows an optional __metadata__ entry of text only: “Arbitrary JSON is not allowed, all values must be strings.”

Loading means parsing the header and reading the tensor bytes. Unlike pickle, the format gives the loader no instructions to follow. PyTorch saves with pickle by default, and a pickle file can carry code that runs when it is loaded. Hugging Face’s README says the main reason for safetensors is “to remove the need to use pickle on PyTorch”.

The byte buffer “cannot contain holes”, which the README says “prevents the creation of polyglot files”, files that read as two formats at once.

Why it matters

Safetensors is meant to close the pickle route to taking over a machine, for weights stored in it. With pickle, Hugging Face’s post says, “it is possible to write a malicious file posing as a model that gives full control of a user’s computer to an attacker”. MITRE ATLAS counts such files among unsafe AI artifacts, which “may exploit deserialization” to run code.

Trail of Bits audited the library, and Hugging Face published the results in May 2023: “No critical security flaw leading to arbitrary code execution was found.” The audit did find missing validation that allowed polyglot files, since fixed. Hugging Face’s post adds that “it is impossible to prove the absence of flaws”.

In practice

The Transformers library loads safetensors weights when a model repository has them. Its documentation says from_pretrained “loads weights stored in the safetensors file format if they’re available” and calls pickle “known to be insecure”.

Getting to safetensors can itself be a risk. Hugging Face ran a service that converted pickle models to safetensors and opened a pull request with the result. In February 2024 HiddenLayer reported that the service loaded the original file with torch.load(), so a malicious pickle could run code inside the converter. They wrote that an attacker could have stolen the bot’s token “to submit pull requests on its behalf to any repository on the site”. HiddenLayer says it told Hugging Face before publishing.

Trade-offs

The safety promise of safetensors is narrower than its name.

The promise covers the weights file only. MITRE ATLAS counts “prompt or chat templates, tokenizer metadata, configuration, pre-processing logic, post-processing logic” as possible unsafe artifacts, and says harm may come through “functionality intentionally supported by an AI runtime” with no software bug at all. A model stored in safetensors can still ship a poisoned chat template beside it. A repository with custom model code still needs trust_remote_code=True to load, and Transformers warns to “avoid inadvertently executing malicious code” when doing so.

The promise is about running code, not about what the weights do. The README’s test of safe asks whether a downloaded file will run code. Nothing in the format tells a loader whether the weights were trained honestly or altered, for example by a backdoor attack. Checking where a file came from is a separate job; see verify AI artifacts.

Questions and answers

Is a safetensors file safe to download and load?

Loading a safetensors file is designed not to run code, which is the danger with pickle. The README defines safe as being able to use a file "randomly downloaded and expect not to run arbitrary code". A 2023 Trail of Bits audit found no critical flaw leading to arbitrary code execution. Safetensors does not check whether the weights are honest, and it does not cover the other files a model repository ships.

Does converting a model to safetensors make it safe?

Converting a model to safetensors removes the pickle route for the weights file only. MITRE ATLAS's definition of unsafe AI artifacts also covers chat templates, tokenizer metadata, configuration and pre- and post-processing logic, which a tensor format does not touch. The conversion step can be a risk too: HiddenLayer reported in 2024 that Hugging Face's conversion service loaded pickle files with torch.load.

What is inside a safetensors file?

A safetensors file holds three parts: eight bytes giving the size of the header, a JSON header that lists each tensor's name, data type, shape and position, and then the raw tensor bytes. An optional metadata entry may hold only text keys and text values.