From Model Files to a Runnable Model
This chapter follows how Ollama turns a human-facing model name or a source weight file into a configured, reusable artifact. The important question is not merely where a model is stored, but what identity, behavior, and resource assumptions travel with it. By the end, the reader should be able to distinguish a tag from the manifest it selects, understand why several model names can share data, and judge whether a customization changes the model’s behavior, its weights, or its memory budget.
A model name resolves to an artifact graph
A model name is an address at the user interface, not the whole object that Ollama runs. Ollama uses a model:tag convention. A model can also have a namespace, and when the tag is omitted the documented default is latest. The tag gives a human-readable way to select a particular model variant, but the runtime needs a more concrete record: a manifest that describes the material making up that variant.
That distinction is easy to miss because the command remains short. A person can ask Ollama to run a name such as llama3.2, while the local system resolves that name to a fully qualified identity and reads its manifest. The manifest contains a configuration layer and an ordered set of content layers. Those layers may represent the main model, a multimodal projector, an adapter, a template, or other material needed to interpret the model. A local model listing can therefore report more than a name: it can expose format, family, parameter size, quantization level, digest, and other metadata.
The manifest is not a directory listing with a different spelling. Its job is to bind an identity to a particular collection of content. Each layer is addressed by a SHA-256 digest. When Ollama creates a layer, it hashes the bytes being written. If a blob with that digest already exists, the layer can reuse it rather than writing an identical copy. If it does not exist, Ollama stores the new blob under its digest and records its size and media type. The digest is therefore both an integrity check and a sharing key.
This arrangement changes the meaning of ordinary model operations. Pulling a model means obtaining a manifest and the layers it names, verifying the downloaded content, and writing the local manifest. Creating a model means assembling a new manifest from an existing model, imported files, or both. Copying a model gives an existing artifact another name without requiring every underlying byte to be duplicated. Deleting a model removes its manifest and can remove layers only when no other manifest still refers to them. The visible commands describe user intent; the artifact graph preserves the consequences.
The reference rule is important in practice. Suppose two model names use the same base weights but have different system messages or sampling defaults. They may need different configuration records while still sharing the large weight blob. If one name is deleted, the shared weight must remain available to the other. Conversely, an unused layer can be pruned once no retained manifest references it. Ollama’s storage code explicitly builds a set of digests still used by other manifests before removing anything. That is a small mechanism with a large operational effect: model cleanup does not have to choose between leaking every old byte and risking the live models.
The same graph also explains why a model’s identity should not be inferred from a filename alone. The repository’s model representation carries a digest, configuration, parent-model information, optional adapter and projector paths, a template, options, messages, and capability information. Some models are backed by GGUF data; Safetensors-backed models use a different native path. What the user calls “the model” is consequently a bundle of learned data and interpretation rules. Two artifacts can begin with related weights and still behave differently because their templates, system messages, adapters, or parser metadata differ.
The diagram is intentionally an artifact view rather than a storage tour. A reference selects a manifest. The manifest binds configuration and content layers. Layers resolve to content-addressed blobs, so different manifests can share bytes. A Modelfile supplies declarative choices for a created artifact; an adapter can add learned adjustments; a quantized derivative can reuse some content while replacing or adding weight data. The exact layer composition depends on the model and operation, but the ownership relationship remains: the manifest says what belongs to the runnable identity, while the blobs hold the bytes.
There is a second useful consequence: the model can be inspected after creation. The API can show the Modelfile representation, template, parameters, system prompt, license, model information, tensor metadata, and capabilities. Inspection does not turn an artifact into a guarantee of quality. It does let a user see which assumptions are being carried into the request path. If a response is unexpectedly formatted, a template or system message is a plausible place to look. If a model consumes more memory than expected, its format and quantization level matter before any prompt is sent.
The lifecycle has an external side as well. Ollama can pull a model from its library, and a user can push a created model to the library after signing in and setting up the required key. The receiving user can then run the published name. This is not the same as proving the model is trustworthy or correctly licensed. The Modelfile can record a license, and the manifest can verify that the bytes match their digest, but neither mechanism independently validates the origin or legal status of every imported weight. Reuse is a property of the artifact system; provenance remains a separate judgment.
Configuration changes the contract, while quantization changes the budget
The Modelfile is Ollama’s declarative boundary for making those judgments explicit. It is described as a blueprint for creating and sharing customized models. Its required FROM instruction identifies the base model, a GGUF file, or a supported Safetensors directory. That source choice determines the learned material from which the new artifact starts. The remaining instructions describe how Ollama should interact with it or which additional learned material should be applied.
A SYSTEM instruction supplies a default system message. TEMPLATE defines the full prompt form sent to the model, using variables for the system message, user prompt, and response. Templates are model-specific because the model’s training convention determines which control tokens or message structure it expects. A template is not decorative presentation. It is part of the input the model receives, so an apparently minor mismatch can change the conversation behavior even when the underlying weights are unchanged.
PARAMETER instructions set generation behavior. The documented options include context size, temperature, random seed, repetition controls, stop sequences, token limits, and sampling controls such as top-k and top-p. These choices alter how the runner generates text, not what the model learned during training. A lower temperature may make output more focused; a fixed seed can support reproducibility; a larger context can make more history available. Each choice has a cost or boundary. A context window consumes memory, a token limit can end an answer early, and reproducibility depends on holding the relevant inputs and runtime conditions stable.
A MESSAGE instruction can embed a conversation history that guides the model toward a style or response pattern. LICENSE records the terms under which the model is shared. REQUIRES records a minimum Ollama version so that a model depending on newer runtime behavior can declare that dependency. These fields show why a model artifact is more than a weight file: the artifact carries an interaction contract and, potentially, a compatibility expectation.
The API does not force every choice to be frozen into a Modelfile. Request-time options can override model defaults, and a request can supply a different system message or template where the endpoint supports it. That flexibility is useful for applications that need per-request behavior, but it introduces another layer of state to inspect. If two clients use the same named model and send different options, the name alone does not predict identical output. The base artifact remains the same while the request contract changes.
Adapters illustrate a sharper boundary between behavior configuration and learned weights. Ollama can apply a LoRA adapter supplied in a supported format. The documentation warns that the base model in FROM must be the same model from which the adapter was tuned; otherwise behavior may be erratic. This is not a naming preference. An adapter contains an adjustment that assumes a particular base representation. Pairing it with a different base can produce a model that is syntactically loadable but semantically unreliable. A successful create operation is therefore not proof that the combination is correct.
Importing makes Ollama useful beyond the models already in its library. A user can create an artifact from a Safetensors directory, a GGUF file, or a compatible adapter, then run the resulting name through the same CLI and API. The server validates paths and digests, detects or converts supported source formats, can infer a template in some conversion flows, and writes a manifest for the result. That pipeline is a bridge between external model tooling and Ollama’s runtime contract. It is also a boundary: support is limited to the architectures and formats recognized by the checked-out release, and a conversion that succeeds still needs testing with the intended prompt and application.
Quantization changes a different variable. It represents model values with fewer bits so the resulting weights use less memory and can run on more modest hardware, generally with some loss of accuracy. Ollama’s import documentation describes quantization as a speed-and-memory benefit purchased with reduced accuracy, and the API exposes selected quantization types for creating a derivative. The right question is not whether quantization is good or bad. It is whether the memory saved is worth the quality change for the task, model, and hardware.
This trade-off becomes more visible when context is included. A quantized weight file may fit where a full-precision file does not, but the runner still needs memory for context and generation work. A long-context application can therefore remain constrained after quantization. Conversely, a smaller quantized artifact may leave enough headroom for a useful context window or several concurrent requests. The artifact’s size is a starting point for capacity planning, not a complete prediction of runtime memory.
The distinction between configuration and weights helps organize a customization decision. If the goal is to change the assistant’s default voice, prompt structure, sampling behavior, or example conversation, a Modelfile may be sufficient. If the goal is to incorporate fine-tuned behavior, an adapter or fused model changes the learned material and brings base-model compatibility into the decision. If the goal is to fit a model into available hardware, quantization changes the memory-quality balance. These operations can coexist, but they should not be described as if they all make the same kind of change.
A practical example shows why the distinction matters. Imagine an application that needs a consistent JSON record from a local model. A system message may tell the model what role to play, a template may ensure the conversation is formatted correctly, and a generation parameter may reduce variation. A schema supplied at request time can further constrain the response format later in the request path. None of these steps guarantees that the extracted facts are correct. The artifact and request can make the output easier to parse, while the application remains responsible for validating the data.
Another example is a coding model that needs a large repository context. Increasing the configured context size can make the task possible, but it raises the runner’s memory requirement. Quantizing the model may create headroom, yet it can change accuracy. Choosing a smaller model may reduce load pressure but alter capability. The artifact layer can expose these options; it cannot decide which compromise is acceptable without knowing the workload.
This is why Ollama’s model-management design is best understood as a controlled transition from source material to a runnable contract. The manifest persists the identity and the bytes. The Modelfile makes behavioral choices reproducible. Import and adapter workflows connect external training or conversion tools to that contract. Quantization adjusts the resource budget with a documented quality boundary. Request-time options can then specialize a particular use without silently changing the underlying artifact.
Once the artifact exists, the next boundary is no longer “where is the file?” It is “what does Ollama do with this configured identity when a client asks for work?” The runtime must resolve the manifest, read its capabilities and prompt rules, combine them with the incoming request, and decide how to load the model. The artifact is therefore not the end of the lifecycle. It is the stateful input that makes the request path possible—and gives that path something precise to inspect when behavior or resource use is unexpected.