§0 The Open-Source Convention — A Universal Reading Order

Before you read any specific fact on this page, internalize the meta-rule it depends on: open-source documentation, including this page, will go stale. That's not a flaw — it's the convention.

This page is dated 2026-04-17, Ollama v0.20.7. Treat every claim below as "true on that date, in that build" — not as eternal scripture. When something stops working months from now, your first move isn't to assume the page lied; it's to ollama serve, watch the dump, and check the recent commits in envconfig/config.go. That habit will outlive any specific name on this page.

§1 TL;DR

Several Ollama "tuning variables" you've seen in blog posts, Stack Overflow answers, and AI assistant outputs were real settings in earlier versions — but the current server (v0.20.7) doesn't read them. They were renamed, replaced, or quietly removed as the project evolved, and Ollama emits no deprecation warning when it encounters them.

Five names whose meaning has drifted out from under tutorials, and what works in the current build:

§2 Ghost Variables — Names That Drifted Out

These names appear in many tutorials, screenshots, and AI-generated configs. They were valid at some point in Ollama's history (or were inherited from llama.cpp by reasonable analogy), but the current server doesn't read them. No deprecation warning, no log line — they're just inert.

Bonus: the inverse case — a non-OLLAMA_* env that does reach the runner

Ghost vars are OLLAMA_*-prefixed names the server doesn't read. The mirror case is more interesting: a non-OLLAMA_*-prefixed env that nonetheless takes effect because of plain POSIX inheritance — and that no public Ollama doc mentions.

grep -m1 'residency set collection' ~/Library/Logs/ollama.log
# expected when env set: ... (keep_alive = 86400 s)
# default (env missing):  ... (keep_alive = 180 s)

§3 The Official 25 Variables

Sourced from envconfig/config.go in Ollama v0.20.7. These are the only OLLAMA_* env vars the server actually parses.

Anything else with the OLLAMA_ prefix that doesn't appear above isn't being read by this version. Good news: the names you'll reach for in production are here — flash attention, KV cache type, keep-alive, host, parallel requests, max loaded models.

This list is a snapshot of v0.20.7. Future releases will add and remove. Re-verify against your local ollama serve startup dump rather than trusting any document — including this one — indefinitely.

§4 Context Length: 3-Tier Priority

This is the most-misunderstood Ollama setting. As of v0.15.5+, the server picks a context length using a three-tier priority chain. Understanding this kills 90% of "why is my context wrong?" confusion.

The Three Tiers (highest priority wins)

1. API request — options.num_ctx in your request body. Beats everything below.
2. Server env var — OLLAMA_CONTEXT_LENGTH at server start. Beats VRAM auto.
3. VRAM auto-detect — server-side default based on available VRAM.

VRAM Auto-Detect Defaults (when nothing else is set)

§5 num_gpu vs OLLAMA_NUM_GPU

The name collision causes endless confusion. Here's the full picture:

What it actually does

On a discrete-GPU system (NVIDIA / AMD), num_gpu controls how many model layers are offloaded to the GPU. Set it to 999 and Ollama puts all layers on GPU (or as many as fit). Lower it to spill layers back to system RAM.

Per-request example (discrete GPU)

import httpx

httpx.post("http://localhost:11434/api/chat", json={
    "model": "llama3.1:70b",
    "messages": [{"role": "user", "content": "Hi"}],
    "options": {
        "num_gpu": 999,        # all layers to GPU
        "num_ctx": 8192,       # context for THIS request
    }
})

§6 Outdated Tutorials, Updated

Each of these was good advice at some point in Ollama's history. The project moved; the advice didn't. None of these are anyone's fault — they're snapshots that aged out.

§7 Correct macOS Server Configs

A. Homebrew ollama serve from your shell

export OLLAMA_HOST=0.0.0.0:11434
export OLLAMA_CONTEXT_LENGTH=131072      # explicit 128K (omit for VRAM-auto)
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
export OLLAMA_KEEP_ALIVE=-1              # never unload
export OLLAMA_NUM_PARALLEL=2             # concurrent requests
export OLLAMA_MAX_LOADED_MODELS=3

# Bonus (Apple Silicon, see §2 bonus box): not an OLLAMA_* var, but
# inherits to the Metal runner via fork/exec. Default 180s causes
# painful first-token latency after idle. 86400 = 24h warm buffers.
export GGML_METAL_RESIDENCY_KEEP_ALIVE_S=86400

ollama serve

B. LaunchAgent plist (auto-start at login)

<key>EnvironmentVariables</key>
<dict>
  <key>OLLAMA_HOST</key>                          <string>0.0.0.0:11434</string>
  <key>OLLAMA_CONTEXT_LENGTH</key>                <string>131072</string>  <!-- NOT OLLAMA_NUM_CTX -->
  <key>OLLAMA_FLASH_ATTENTION</key>               <string>1</string>
  <key>OLLAMA_KV_CACHE_TYPE</key>                 <string>q8_0</string>
  <key>OLLAMA_KEEP_ALIVE</key>                    <string>-1</string>
  <key>GGML_METAL_RESIDENCY_KEEP_ALIVE_S</key>    <string>86400</string>  <!-- ggml-layer (§2 bonus) -->
</dict>

C. The Ollama.app GUI gotcha

launchctl setenv OLLAMA_CONTEXT_LENGTH 131072
launchctl setenv OLLAMA_FLASH_ATTENTION 1
launchctl setenv OLLAMA_KV_CACHE_TYPE q8_0

# Then quit and relaunch Ollama.app

Option 2: use the Settings UI inside recent Ollama.app builds — there's a context-length slider and a few performance toggles.

§8 Verify Your Config

Ollama dumps every config it recognizes at server startup. This is the ground truth.

$ ollama serve

time=2026-04-17T10:32:15Z level=INFO source=routes.go:1742 \
  msg="server config" \
  env="map[OLLAMA_CONTEXT_LENGTH:131072 \
       OLLAMA_DEBUG:INFO \
       OLLAMA_FLASH_ATTENTION:true \
       OLLAMA_GPU_OVERHEAD:0 \
       OLLAMA_HOST:http://0.0.0.0:11434 \
       OLLAMA_KEEP_ALIVE:-1 \
       OLLAMA_KV_CACHE_TYPE:q8_0 \
       OLLAMA_MAX_LOADED_MODELS:3 \
       OLLAMA_NUM_PARALLEL:2 \
       ...]"

Quick one-liner to check defaults

# Restart server, capture first 50 lines
ollama serve 2>&1 | head -n 50 | grep -E "server config|total_vram|default_num_ctx"

You'll see your env vars and the auto-detected VRAM-based context default in one shot.

Bonus: verify the ggml-layer env (§2 bonus)

The map[...] dump only covers OLLAMA_* vars. To confirm a non-Ollama env like GGML_METAL_RESIDENCY_KEEP_ALIVE_S reached the runner, check two places:

# 1. Is the env on the live server process?
ps eww $(pgrep -f 'ollama serve' | head -1) | tr ' ' '\n' | grep -E 'OLLAMA_|GGML_'

# 2. Did the runner actually use it on model load?
grep -m1 'residency set collection' ~/Library/Logs/ollama.log
# expected: ... (keep_alive = 86400 s)
# default:  ... (keep_alive = 180 s)

Same principle generalizes: any env from a library Ollama links against (ggml, Metal, CUDA) won't show up in Ollama's own startup dump but can still take effect via standard POSIX fork/exec inheritance. ps eww on the live process and the runner's own log lines are the only way to confirm.

§9 Sources

• envconfig/config.go — definitive list of recognized env vars
• api/types.go — definitive list of API request options (num_ctx, num_gpu, etc.)
• Issue #14130 — maintainer confirmation that OLLAMA_NUM_GPU/OLLAMA_NUM_CTX/OLLAMA_MAX_CONTEXT are not config variables
• PR #8938 — introduction of OLLAMA_CONTEXT_LENGTH (Feb 2025)
• docs.ollama.com/faq
• docs.ollama.com/context-length
• ggml-org/ggml — embedded library that owns the Metal backend and reads GGML_METAL_RESIDENCY_KEEP_ALIVE_S directly
• Field discovery (§2 bonus) — GGML_METAL_RESIDENCY_KEEP_ALIVE_S behavior was learned by runner-log inspection on a production Apple Silicon fleet (Mac Studio M3 Ultra). Not documented in any Ollama-side source as of v0.20.7. Re-verify on future releases.