OLLAMA_NUM_CTX Is Not an Ollama Setting: How to Actually Set the Context Length

TL;DR: OLLAMA_NUM_CTX is not an environment variable Ollama’s server reads. ollama serve --help lists the variables it recognizes, and OLLAMA_NUM_CTX isn’t one of them, so it gets silently ignored. Set the context with OLLAMA_CONTEXT_LENGTH for a server-wide default or the num_ctx option per request, then confirm it worked with ollama ps, which shows a CONTEXT column for every loaded model.

OLLAMA_NUM_CTX shows up constantly in setup guides, forum threads, and copy-pasted .env files, because it looks exactly like the kind of environment variable Ollama would read. It isn’t. The model still loads. Nothing errors. It just runs at whatever context length Ollama picked on its own, which is rarely the number you meant to set.

Contents

• Why OLLAMA_NUM_CTX Does Nothing
• How to Check the Context a Model Is Really Using
• The Four Ways That Actually Set the Context Length
• OpenAI-Compatible Clients Have No Field for This
• How Big to Set It
• The Docker Gotcha: Recreate, Not Restart

Why OLLAMA_NUM_CTX Does Nothing

Ollama’s server tells you exactly which environment variables it reads. Run ollama serve --help and look at the output. OLLAMA_CONTEXT_LENGTH is listed there, described as “Context length to use unless otherwise specified (default: 4k/32k/256k based on VRAM).” OLLAMA_NUM_CTX does not appear anywhere in that list, because the server was never written to look for it.

An environment variable the server doesn’t recognize doesn’t produce a warning. It doesn’t fail the start. It just sits there, unread, while Ollama proceeds with whatever default it would have used anyway.

We confirmed this directly, on Ollama 0.34.1 in the official Docker image. With OLLAMA_NUM_CTX=24576 set in the environment, a request sent with no num_ctx option loaded the model at 32768 tokens: the VRAM-based default for that card, not the 24576 the environment variable claimed to set. The same request, this time with "options": {"num_ctx": 24576} included in the payload, loaded the model at 24576 as expected.

Same environment, same model, two different outcomes, and the only thing that changed was whether the setting arrived as an environment variable or as a request option.

The confusion is easy to understand. num_ctx is a real, working setting name. It’s the option key in the request payload, the parameter name inside a Modelfile, and the flag you type into /set parameter num_ctx during an interactive session. Ollama configures several other things through OLLAMA_-prefixed environment variables, so assuming num_ctx follows the same pattern is a reasonable guess. It’s just the wrong one for this particular setting, and it has been copied into enough guides and forum answers that it now reads as established practice rather than a mistake.

How to Check the Context a Model Is Really Using

Don’t trust a variable name to tell you what took effect. Check the running model directly.

ollama ps

The output includes a CONTEXT column showing the context length the currently loaded model is actually running at. This is the verification step for everything in this post: after you change a setting and send a request, run ollama ps and read the CONTEXT column before assuming anything worked.

Two details matter here. First, a model only shows up in ollama ps while it’s loaded, so run the command right after a request, not minutes later once it’s been unloaded. Second, this is the only check that reflects reality. The setting you think you applied and the context the model is actually running at are two different claims, and only one of them is verifiable from the command line.

The Four Ways That Actually Set the Context Length

These are the settings Ollama’s own documentation describes as the real ways to control context length. Pick based on scope: do you want every model on this server to default to a size, or does one request need a specific value?

Server-wide default, applied when the server starts:

OLLAMA_CONTEXT_LENGTH=8192 ollama serve

Per request, inside the options object on /api/generate or /api/chat:

{
  "model": "llama3",
  "prompt": "...",
  "options": {
    "num_ctx": 8192
  }
}

Interactive, inside an ollama run session:

/set parameter num_ctx 8192

Baked into a model, so every future load of that model uses the value without anyone having to remember to set it. Write a Modelfile:

FROM llama3
PARAMETER num_ctx 8192

Then build it:

ollama create my-model -f Modelfile

A request’s num_ctx option overrides the server-wide default. If you layer a Modelfile value on top of the environment variable as well, don’t assume which one wins: check ollama ps.

OpenAI-Compatible Clients Have No Field for This

If you’re talking to Ollama through its OpenAI-compatible endpoint, the request body has no field for context length at all. Ollama’s own compatibility documentation says to set the context size in a Modelfile instead, because the /v1 request shape simply doesn’t carry a num_ctx-equivalent parameter.

That leaves two real options for an OpenAI-compatible client: bake the context length into the model with a Modelfile, or rely on the server-wide OLLAMA_CONTEXT_LENGTH default. There’s no per-request override available through that endpoint, so whichever of those two you choose needs to already match what the workload requires before the request goes out.

How Big to Set It

Bigger isn’t free, and it isn’t unlimited either.

Ollama silently caps whatever you request to the model’s trained maximum. This is handled internally as an effective context calculation, and it means a request for num_ctx of 1,000,000 tokens on a model trained for 262,144 tokens will simply run at 262,144. No error, no warning, just a quiet ceiling.

Below that ceiling, the cost is memory. A larger context window means a larger KV cache, and a larger KV cache means more VRAM committed to that model, on top of the model’s own weights. Ollama’s documentation also notes that this scales further with concurrency: multiple parallel requests to the same model multiply the context memory by the number of parallel requests allowed, a setting controlled separately through OLLAMA_NUM_PARALLEL. None of this shows up as an error either. It shows up as memory use, and ollama ps helps here too: its PROCESSOR column reports how much of the loaded model sits on the GPU and how much has spilled to the CPU.

This matters most for agent-style workloads, where the context has to hold tool definitions and conversation history on top of the actual task, and a context size that looked generous for a chat prompt turns out to be tight once an agent framework is filling it with system instructions on every turn. If you’re running Ollama behind an agent setup and sizing context for that specific pressure, our OpenClaw + Ollama local LLM guide covers that workload in more depth.

The Docker Gotcha: Recreate, Not Restart

If Ollama runs in a container, changing an environment variable in your compose file and then running docker restart will not apply it. A restart brings the same container back up with the same environment it already had. The variable only gets re-read when the container is recreated: docker compose up -d after editing the file, or a full down followed by up.

This produces a specific, confusing failure: you edit OLLAMA_CONTEXT_LENGTH, restart the container, run a request, and the context is exactly what it was before, because the process never actually saw the new value. It’s the same category of failure as the environment variable Ollama doesn’t read in the first place: a change you made that had no effect, with nothing telling you it didn’t take. We cover several other silent failures like this, where the fix looks like it should have worked and didn’t, in our OpenClaw production gotchas rundown.

Self-hosted model serving has more of these gaps than the documentation admits, and most of them fail silently rather than loudly. If you’re running Ollama or another local model stack behind an agent setup in production, this is the kind of thing our AI agent development work sorts out before it costs you a debugging afternoon. Book a discovery call and we’ll walk through your setup.

Soli Deo Gloria