A Modelfile is the blueprint Ollama uses to create and share a customized model. It is a plain text file that answers three practical questions: which base model should be loaded, how should that model be run, and what standing instructions should shape its behaviour. Once the file exists, a single ollama create command turns it into a named model you can run like any other.
This guide is written for technically curious beginners and intermediate practitioners who already have Ollama installed and want to move beyond running a stock model. It covers the file format, a working example, the parameters worth understanding, verification, and the failure modes that come up most often.
What a Modelfile actually controls
According to Ollama’s Modelfile reference, the file uses a simple instruction-and-arguments format, with comments introduced by #:
# comment
INSTRUCTION argumentsThe documented instructions are:
| Instruction | Purpose |
|---|---|
FROM (required) | Defines the base model to use. |
PARAMETER | Sets the parameters for how Ollama will run the model. |
TEMPLATE | The full prompt template to be sent to the model. |
SYSTEM | Specifies the system message that will be set in the template. |
LICENSE | Specifies the legal license. |
MESSAGE | Specify message history. |
REQUIRES | Specify the minimum version of Ollama required by the model. |
CAPABILITY | Declare an additional model capability. |
For most customizations, only three of these matter: FROM, PARAMETER, and SYSTEM. The TEMPLATE instruction is more invasive — it replaces the full prompt structure sent to the model — and is usually only needed when adapting a base model whose expected chat format differs from Ollama’s default. If you override the template, be aware that the system message is injected through it, so a hand-written template can change or bypass how your SYSTEM text reaches the model.
Prerequisites
- Ollama installed and working on the machine where you plan to build the model.
- A base model already available locally. The official example uses
llama3.2; the KodeKloud walkthrough uses the same base. - A text editor and access to a terminal.
The examples below follow the documented workflow. They are illustrative configurations rather than results from a controlled test run, so treat the exact wording of any system prompt as a starting point to adapt.
Building a custom model, step by step
1. Create the file
Ollama does not require a specific filename, but convention is a file literally named Modelfile. The KodeKloud tutorial creates and opens one like this:
touch Modelfile
code ModelfileSubstitute your own editor if you do not use VS Code.
2. Declare the base model
The first meaningful line must be FROM, because the base model is the only required instruction. A minimal file is therefore:
FROM llama3.2You can point FROM at an existing Ollama model, a Safetensors model, or a GGUF model — all three are documented build paths. Starting from an existing Ollama model is the simplest option and is what the official basic example does.
3. Add parameters
Parameters control how the model runs rather than what it knows. The official example sets temperature and context window together:
FROM llama3.2
# sets the temperature to 1 [higher is more creative, lower is more coherent]
PARAMETER temperature 1
# sets the context window size to 4096, this controls how many tokens the LLM can use as context to generate the next token
PARAMETER num_ctx 4096The KodeKloud financial-assistant demo takes the opposite approach for a task where consistency matters more than variety, using PARAMETER temperature 0.3.
4. Add a system prompt
The SYSTEM instruction supplies a standing message that shapes tone, role, and scope. The official example is deliberately short:
SYSTEM You are Mario from super mario bros, acting as an assistant.The KodeKloud example is more structured, naming the assistant, the organisation, and the domain:
SYSTEM You are Harris, an AI assistant for the employees of an investment and portfolio management firm called Growmore. Your job is to assist employees in managing client investments and portfolios. The currency you deal with is Indian Rupees (INR).The pattern worth copying is the level of specificity: role, audience, and any domain constraints that would otherwise have to be repeated in every conversation.
5. Build and run
The documented sequence is:
ollama create choose-a-model-name -f Modelfile
ollama run choose-a-model-nameReplace choose-a-model-name with something descriptive, such as growmore-assistant. A successful build ends with the model registered locally, and ollama run drops you into an interactive session with it. To confirm the behaviour changed, ask a question that only makes sense inside your system prompt’s context — for the example above, a question about INR-denominated portfolios.
Parameters worth understanding before you tune them
Two parameters appear in both official and tutorial examples and are the ones most readers will touch first.
temperature governs sampling randomness. The documentation’s inline comment summarises the tradeoff plainly: higher is more creative, lower is more coherent. A low value such as 0.3 suits extraction, classification, and factual drafting; a higher value suits brainstorming and prose variation.
num_ctx sets the context window, described in the documentation as controlling how many tokens the model can use as context to generate the next token. This is the parameter with the clearest resource consequences. A larger context window increases memory use beyond the model weights themselves, because the runtime must hold the key/value cache for the tokens in context. If you raise num_ctx on a machine with limited memory, expect slower generation or out-of-memory failures rather than a free accuracy improvement.
Ollama’s parameter set also includes sampling controls such as top_p and top_k, repetition handling, output-length limits, and stop sequences. These are established parts of the runtime, but their exact names and accepted ranges should be checked against the current Modelfile reference rather than copied from older blog posts, since parameter lists change between releases.
Inspecting an existing model’s Modelfile
Before writing your own, it is worth reading one that already works. The documented command is:
ollama show --modelfile llama3.2The output is generated by Ollama and includes a header comment explaining how to reuse it, along with a line such as # To build a new Modelfile based on this one, replace the FROM line with: followed by the model tag. This is the fastest way to see which template and parameters a stock model ships with, and it gives you a correct starting point for a derivative model.
Common problems and how to diagnose them
The build fails immediately
Check that FROM is present and that the referenced model actually exists locally. Because FROM is the only required instruction, a missing or misspelled base model is the most common cause of a failed ollama create.
The model runs but ignores the system prompt
First confirm you are running the new model name and not the base model — it is easy to build my-assistant and then type ollama run llama3.2 out of habit. Second, check whether the file also contains a TEMPLATE instruction. A custom template changes how the system message is delivered, and a template that omits the system slot will silently discard your SYSTEM text.
Output is repetitive, rambling, or truncated
These symptoms point at parameters rather than the system prompt. Very low temperature can make output repetitive; a small num_ctx can cause earlier conversation content to fall out of context; an output-length limit can cut responses short. Change one parameter at a time and rebuild so you can attribute the difference.
Memory pressure after raising num_ctx
Reduce num_ctx and rebuild. Weight size alone is not a reliable guide to total memory use, because the context cache and runtime overhead add to it.
Limitations and tradeoffs
A Modelfile does not change the model’s weights, and it does not add knowledge the base model lacks. It configures how an existing model is loaded and prompted. That means a system prompt can shape tone and constrain scope, but it cannot make a small model authoritative on a domain it was never trained for; retrieval or fine-tuning are the appropriate tools for that.
Parameters are part of the derived model’s definition, so two different configurations generally mean two different model names, each built from its own Modelfile. Keeping those files in version control alongside the prompts they contain is a practical habit, because a system prompt edit is a behaviour change and deserves the same traceability as code.
Where this fits in a broader workflow
A named custom model is easier to wire into automation than a bare base model plus a long prompt pasted at call time. As an illustrative design — not a deployed case study — a content team might define one Modelfile with a low temperature and a system prompt describing house style, build it as house-style-drafter, and have a WordPress publishing workflow call that model for first drafts while a human editor reviews output before anything is published. The system prompt then lives in one file rather than being duplicated across scripts.
Next actions
Run ollama show --modelfile against the model you use most often, copy the output into a new file, and change exactly one thing: add a SYSTEM line describing your own use case. Build it under a new name, compare the two models on the same prompt, and only then start tuning temperature or num_ctx. If a build fails or the behaviour diverges from what you expected, share your Modelfile contents (minus anything sensitive), your Ollama version, and the exact error text with the community so others can reproduce it.
FAQ
Does creating a Modelfile retrain or modify the model?
No. The Modelfile defines which base model to use and how to run it — parameters, template, and system message. It does not alter the model's weights or add new knowledge.
Can I read the Modelfile of a model I already have?
Yes. Run ollama show --modelfile followed by the model name; Ollama generates the file, including a comment showing how to rebuild from it by replacing the FROM line.
Why does my custom model behave the same as the base model?
The most common causes are running the base model name instead of the new one, or a custom TEMPLATE instruction that does not pass the system message through to the model.
Does a larger num_ctx always improve results?
Not necessarily. It lets the model consider more tokens, but it also increases memory use and can slow generation. Raise it only when your prompts genuinely need the extra context.