Pulling qwen3:8b and chatting is the easy part. The hard part is making the same base model behave like a coding assistant, a translator, or a careful summariser, without writing a separate wrapper. Ollama’s answer is a plain-text file called Modelfile and eight documented instructions that, together, hold everything a model needs to run: the base weights, a system prompt, sampling parameters, a prompt template, a license, an optional pre-seeded conversation, declared capabilities, and the minimum Ollama version. This page walks through what each instruction does, when it is worth editing, and what changes to make for the three customisations a typical local setup actually needs.
What a Modelfile Is and Is Not
A Modelfile is a Dockerfile-style text file, one instruction per line, that Ollama reads with ollama create to produce a named model on your machine. The created model is a new tag, not an edit of the upstream model. The ollama show --modelfile <name> command prints the Modelfile of a model in your local store, so you can inspect what a given tag actually contains (Ollama Modelfile Reference).
A Modelfile is not the GGUF weights themselves. The weights come from the FROM line. The Modelfile only describes how to run them: which sampling knobs to set, which chat template to wrap them in, what system prompt to inject. If you want to load raw weights without writing a full Modelfile, the import flow still uses a minimal one: FROM /path/to/file.gguf for a single file or FROM /path/to/model-*.gguf for a split GGUF, then ollama create my-model (Ollama Import documentation).
The Ollama repository itself is MIT-licensed, so the runtime and the Modelfile feature are both under MIT (Ollama repository metadata). The license of the resulting model is governed by the weights you point FROM at, not by Ollama: the LICENSE instruction “allows you to specify the legal license under which the model used with this Modelfile is shared or distributed”, so if the model card says Apache-2.0, that is the licence to record, and a LICENSE line keeps it visible.
The Eight Modelfile Instructions
The reference lists eight instructions, of which only FROM is required (Ollama Modelfile Reference). The rest are optional and the Modelfile is not case sensitive; capitalisation in the table below matches the reference to make the file easier to read.
| Instruction | What it does | When to use it |
|---|---|---|
FROM (required) | Picks the base weights: a tag like qwen3:4b, a Hugging Face Safetensors directory, or a path to one or more GGUF files (shards via * glob) | Always; the reference notes instructions can be in any order, but its examples put FROM first for readability |
PARAMETER | Sets one of the eleven sampling or runtime values (full table in the next section) | When you want the default knob to differ from the base model’s defaults for a specific role |
TEMPLATE | Replaces the chat template that wraps system, user, and assistant messages | When you import raw weights with no chat template, or when you want a different format from the base tag |
SYSTEM | Sets the system message used in the template | When the role of the customised model is different from the role the base model was trained for |
LICENSE | Attaches a human-readable license block to the tag you create | When the upstream model card is silent or you want the licence recorded on the model itself |
MESSAGE | Pre-loads a role-tagged exchange (system, user, or assistant) into the conversation history | When a few-shot example is worth more than a paragraph of system text |
CAPABILITY | Declares an additional capability (for example decision) on a GGUF or MLX model without removing inherited or inferred capabilities | When you are running decision prompts and want the tag to advertise that; per the reference, declare decision only for weights trained for System One’s decision prompts |
REQUIRES | Pins the minimum Ollama version the tag will load under (for example REQUIRES 0.14.0) | When the tag depends on a feature that only exists in recent Ollama builds |
The Eleven PARAMETER Values
PARAMETER is the most-edited instruction, and the reference lists eleven valid values. The defaults in the table are the ones the reference page lists (Ollama Modelfile Reference). A base tag can ship its own values, which a Modelfile built FROM it starts from: the qwen3:4b tag sets temperature 0.6, top_k 20, top_p 0.95 and repeat_penalty 1. For num_ctx, Ollama’s FAQ gives a default context window of 4096 tokens, not the reference’s 2048. Options such as num_gpu and num_thread do not appear in the reference’s parameter table, so they are not in this one.
| Parameter | Type | Default | Effect |
|---|---|---|---|
num_ctx | int | 2048 | Size of the context window used to generate the next token; raise to fit longer prompts |
num_predict | int | -1 (infinite) | Maximum tokens to generate; set to a finite number to bound latency and cost |
repeat_last_n | int | 64 (0 = disabled, -1 = num_ctx) | Window the model looks back to when applying the repeat penalty |
repeat_penalty | float | 1.0 (disabled) | Strength of the repetition penalty; raise above 1.0 to suppress loops |
temperature | float | 0.8 | Higher = more creative; the parameter table’s example is temperature 0.7 |
top_k | int | 40 | Limits the candidate token pool; lower = more focused, higher = more diverse |
top_p | float | 0.9 | Works together with top_k; higher = more diverse text, lower = more focused and conservative text |
min_p | float | 0.0 | Alternative to top_p; tokens below min_p * max_token_prob are filtered, default 0.0 disables it |
seed | int | 0 | Random seed; same prompt + same seed = same output, useful for reproducible tests |
stop | string | (none) | One or more stop strings; multiple stop lines register multiple patterns, useful for cutting off chat-template tokens |
draft_num_predict | int | (none) | Maximum speculative draft tokens per step when a draft model is available; separate draft models default to 4, embedded MTP tensors require an explicit value, and 0 disables speculative drafting entirely |
draft_num_predict is in the eleven as listed above; it sits at the speculative end of the table. Per the reference, separate draft models default to 4, embedded MTP (multi-token-prediction) tensors require setting this parameter, and setting it to 0 disables speculative drafting.
Three Real Modelfiles Worth Copying
Every Modelfile starts with FROM <name>:<tag>. Picking the base tag is the editorial choice; the rest is plumbing. The Ollama model library is where tag names and sizes live (Ollama library), and a current chat-tuned tag like qwen3:4b is published under the Apache License 2.0 with a chat template already attached, so the Modelfile only needs to set the role-specific bits (Qwen3-4B model card).
A Modelfile for a careful, deterministic coding helper:
FROM qwen3:4b
PARAMETER temperature 0.2
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
SYSTEM """You are a careful coding assistant. Answer in code blocks. If you are not sure, say so instead of inventing an API."""
LICENSE """Apache-2.0 - see https://huggingface.co/Qwen/Qwen3-4B"""A Modelfile for a translation helper that always returns the target language only:
FROM qwen3:4b
PARAMETER temperature 0.3
PARAMETER num_predict 1024
SYSTEM """Translate the user's text into English. Output only the translation, no commentary, no quotes."""
MESSAGE user Traduisez: bonjour le monde
MESSAGE assistant Hello world
MESSAGE user Traduisez: gracias por todo
MESSAGE assistant Thank you for everythingA Modelfile for an offline summariser with bounded output:
FROM qwen3:4b
PARAMETER temperature 0.4
PARAMETER num_predict 400
PARAMETER repeat_penalty 1.1
SYSTEM """Summarise the user's text in three short bullet points. Use British English. Do not add facts that are not in the source."""The three Modelfiles are intentionally small. The Modelfile is not where you put the prompt; the chat template handles the formatting, PARAMETER handles the knobs, and SYSTEM is a short instruction plus the role. Long instructions belong in a system message the user sends at conversation time, not in the file.
Deploying a Modelfile Change Without Breaking Your Setup
Editing a Modelfile and running it is a one-liner; the safe workflow is a one-liner plus a small habit. The reference’s deploy procedure is ollama create <name> -f <path to Modelfile> and then ollama run <name> to test (Ollama Modelfile Reference). Two habits make the change reversible:
Give the new tag a new name. A Modelfile that creates coding-helper-v2 instead of overwriting coding-helper leaves the previous tag on disk, so a bad change is a one-command rollback. The import documentation uses ollama cp to copy a model to a new name (for example before pushing it under your username to ollama.com) (Ollama Import documentation).
Inspect before you run. The ollama show --modelfile <name> command prints the Modelfile of a tag in your local store. Read it once after ollama create to confirm that the SYSTEM, PARAMETER, TEMPLATE and stop lines you expected are the ones that got stored.
For imports, the import docs make the same point from the other side: Ollama does not quantise GGUF models during import, so the file you point FROM at must already be the quantisation you want; the docs point to llama.cpp’s llama-quantize for that step (Ollama Import documentation).
Bottom Line
The Modelfile is the right place for the things that should not change between conversations: a stable role (SYSTEM), a stable sampling profile (PARAMETER), and a stable template if you are importing raw weights. The right place for the things that should change between conversations is the chat itself. Treat the Modelfile as small, named, and versioned, and the local setup becomes easier to reason about than a prompt that tries to do everything at conversation time.