Manifest and blobs

The on-disk format Ollama uses to store models. Inspired by OCI distribution: a JSON manifest references content-addressed blobs.

On-disk layout

$OLLAMA_MODELS/                            # default ~/.ollama/models
├── manifests/
│   └── <host>/<namespace>/<model>/<tag>   # JSON manifest, e.g. registry.ollama.ai/library/gemma3/latest
└── blobs/
    └── sha256-<digest>                    # content-addressed blob (weights, template, license, etc.)

OLLAMA_MODELS is read in envconfig/config.go.

Manifest shape

{
  "schemaVersion": 2,
  "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
  "config": {
    "mediaType": "application/vnd.docker.container.image.v1+json",
    "digest": "sha256:...",
    "size": 567
  },
  "layers": [
    { "mediaType": "application/vnd.ollama.image.model",    "digest": "sha256:...", "size": ... },
    { "mediaType": "application/vnd.ollama.image.template", "digest": "sha256:...", "size": ... },
    { "mediaType": "application/vnd.ollama.image.license",  "digest": "sha256:...", "size": ... },
    { "mediaType": "application/vnd.ollama.image.params",   "digest": "sha256:...", "size": ... },
    { "mediaType": "application/vnd.ollama.image.system",   "digest": "sha256:...", "size": ... }
  ]
}

Specific media types Ollama uses include application/vnd.ollama.image.model (GGUF weights), application/vnd.ollama.image.adapter, application/vnd.ollama.image.projector, application/vnd.ollama.image.template, application/vnd.ollama.image.system, application/vnd.ollama.image.params, and application/vnd.ollama.image.license. The exact list is defined in manifest/.

Key abstractions

Symbol	Location	Purpose
manifest.Manifest	manifest/	Top-level type with config + layers.
manifest.Layer	manifest/	One blob's metadata: mediaType, digest, size.
Server.GetModel(name)	server/images.go	Read a manifest off disk into a runtime Model.
Server.fixBlobs	server/fixblobs.go	Boot-time consistency check that prunes orphan blobs and dangling manifests.
Server.CreateBlobHandler, HeadBlobHandler	server/routes.go	The local OCI-like upload routes used by ollama create.

Lifecycle

• Pull: Server.PullHandler (server/download.go) fetches the manifest from the registry, then HEADs each layer's digest against the local store and downloads the missing ones.
• Push: Server.PushHandler (server/upload.go) HEADs each layer against the registry, uploads missing ones, then PUTs the manifest.
• Create: Server.CreateHandler (server/create.go) writes a new manifest from a CreateRequest whose layers were uploaded through CreateBlobHandler.
• Show: Server.ShowHandler (server/routes.go) reads the manifest and emits a structured view.

Garbage collection

Server.fixBlobs runs at startup. It:

1. Lists every blob under blobs/.
2. Walks every manifest under manifests/.
3. Deletes manifests pointing at missing blobs.
4. Deletes blobs not referenced by any manifest.

OLLAMA_NOPRUNE=1 skips the cleanup, which is useful when the model directory is shared between hosts (one host's manifests might reference blobs another host hasn't pulled yet).

Integration points

• Storage: storage and registry.
• Modelfile create: primitives/modelfile.
• The scheduler reads layer metadata to size context for fit decisions.

Key source files

File	Purpose
manifest/	Manifest types.
server/images.go	Local store, GetModel.
server/download.go	Pull.
server/upload.go	Push.
server/fixblobs.go	Garbage collection.
fs/gguf/	GGUF reader for model layers.