Storage and registry

How models are stored locally and exchanged with the registry. Spans server/images.go, server/download.go, server/upload.go, manifest/, fs/gguf/, and fs/ggml/.

Purpose

Treat a model as a content-addressed bundle of blobs (weights, projector, license, params, template) tied together by a manifest. Pulls and pushes look like OCI: HEAD-then-PUT for blobs, fetch and verify the manifest, garbage-collect orphans.

Layout on disk

$OLLAMA_MODELS/                   # default ~/.ollama/models
├── manifests/
│   └── registry.ollama.ai/
│       └── library/
│           └── gemma3/
│               └── latest        # JSON manifest
└── blobs/
    ├── sha256-<digest>           # e.g., quantized weights
    ├── sha256-<digest>           # template
    └── sha256-<digest>           # license

OLLAMA_MODELS and the registry origin (OLLAMA_REGISTRY etc.) are read through envconfig/config.go.

Key abstractions

Symbol	Location	Purpose
Manifest	manifest/manifest.go	OCI-ish JSON descriptor: mediaType, config, layers, each pointing at a digest.
Layer	manifest/	One blob's metadata: mediaType, digest, size.
Model	server/model.go	Server-side hydrated model: paths to weights/projector/adapter, parsed template, options, capabilities.
GetModel	server/images.go	Hydrate Model from a manifest on disk.
Server.PullHandler	server/download.go, server/routes.go	Download manifest then blobs from the registry, retry chunks on failure.
Server.PushHandler	server/upload.go, server/routes.go	Upload missing blobs and the manifest.
Server.CreateBlobHandler / HeadBlobHandler	server/routes.go	Local equivalents of OCI HEAD/PUT used during ollama create.
Server.fixBlobs	server/fixblobs.go	Boot-time consistency check.
fs/gguf	fs/gguf/	Reads/writes GGUF files.
fs/ggml	fs/ggml/	Higher-level GGML helpers (used by the scheduler to peek at metadata).

How it works

sequenceDiagram
    participant CLI
    participant Daemon as ollama serve
    participant Registry as registry.ollama.ai

    CLI->>Daemon: POST /api/pull
    Daemon->>Registry: GET /v2/library/gemma3/manifests/latest
    Registry-->>Daemon: manifest JSON
    Daemon->>Daemon: write manifest to disk (atomic rename)
    loop for each layer
        Daemon->>Daemon: blob already on disk? (sha256 match)
        alt missing
            Daemon->>Registry: GET /v2/library/gemma3/blobs/<digest>
            Registry-->>Daemon: stream
            Daemon->>Daemon: write to blobs/sha256-<digest> (atomic)
        end
    end
    Daemon-->>CLI: NDJSON progress stream

PullHandler chunks downloads, retries on transient errors, and reports progress as NDJSON (server/download.go).

PushHandler is the inverse: HEAD each blob's digest against the registry, PUT only the missing ones, then PUT the manifest. Both honor Authorization headers built from the user's SSH key (see auth).

Create flow

ollama create <name> calls parser.ParseFile (parser/parser.go) to parse the Modelfile. The CLI:

1. For each FROM / ADAPTER / MESSAGE directive that references a file, reads it, computes sha256, and uploads it through POST /api/blobs/:digest if the daemon doesn't already have it.
2. Sends the resulting CreateRequest to POST /api/create.

The server-side CreateHandler (server/routes.go) assembles the manifest, writes it under manifests/, and returns success.

The --experimental flag on ollama create triggers a different path through x/create/ for safetensors-based creation, which writes a Modelfile-equivalent and then walks the same blob upload pipeline.

Garbage collection

fixBlobs (server/fixblobs.go) runs at startup. It removes any blob that isn't referenced by a manifest and any manifest that points at missing blobs. Set OLLAMA_NOPRUNE=1 to skip it (useful when sharing a ~/.ollama/models directory between hosts).

Cloud-only models

A subset of model names resolve to ollama.com's cloud inference rather than local blobs. model_resolver.go (server/model_resolver.go) decides, and inference handlers route through the cloud proxy when the resolver flags the model as cloud-only. See cloud proxy.

Integration points

• The Modelfile parser (primitives/modelfile) feeds the create flow.
• The scheduler (via server/images.go's Model) calls into the GGUF/GGML helpers to size context for fit decisions.
• The registry endpoints honor the user's signin token from auth.

Entry points for modification

• New media type → add it to the manifest helpers in manifest/ and the create / show paths in server/routes.go.
• New retry policy or chunk size → tweak download.go / upload.go.
• New garbage-collection rule → extend fixBlobs.

Key source files

File	Purpose
manifest/	Manifest types and serialization.
server/images.go	Local model store, GetModel, manifest writes.
server/download.go	Pull from registry.
server/upload.go	Push to registry.
server/fixblobs.go	Boot-time consistency check.
server/model_resolver.go	Cloud-vs-local resolution.
fs/gguf/	GGUF parser.
fs/ggml/	GGML metadata helpers.