Ollama Environment Variables

A field reference for version drift on a fast-moving OSS project

Verified against Ollama v0.20.7 (2026-04-17). Ollama renames, removes, and quietly drops env vars between releases. Names like OLLAMA_NUM_CTX, OLLAMA_NUM_GPU, and OLLAMA_MLX were valid in older versions but the current server silently ignores them — no deprecation warning, no log line. This guide is a snapshot of what is recognized right now, and the discipline you need to keep up.

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

Before any specific fact on this page, internalize the meta-rule it depends on: open-source documentation, including this page, will go stale. That is not a flaw — it is 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 recent commits in envconfig/config.go.

§1 TL;DR — five names whose meaning has drifted out

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

Name (no longer recognized)	What it used to do / was meant to do	What works in v0.20.7
`OLLAMA_NUM_CTX`	Server-wide context length	`OLLAMA_CONTEXT_LENGTH` (env) or `options.num_ctx` (per request)
`OLLAMA_NUM_GPU`	Force layers to GPU at server level	Per-request `options.num_gpu` or Modelfile `PARAMETER num_gpu` (discrete GPUs only)
`OLLAMA_N_GPU_LAYERS`	llama.cpp-style layer offload	Same as above
`OLLAMA_MLX`	Toggle MLX backend on Apple Silicon (preview era)	Not present in current envconfig. Apple Silicon ships on the Metal backend; for MLX-native, run `mlx-lm` directly.
`OLLAMA_MAX_CONTEXT`	Cap server context	`OLLAMA_CONTEXT_LENGTH`

§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.

Name	Why people set it	Status in v0.20.7 / what to use today
`OLLAMA_NUM_CTX`	"Sets default context window"	Renamed. Maintainer note in issue #14130 confirms it's not a current config var. Use `OLLAMA_CONTEXT_LENGTH`.
`OLLAMA_NUM_GPU`	"Force all layers to GPU at server level"	Not in current envconfig. The layer-count knob lives at request time: API `options.num_gpu` or Modelfile `PARAMETER num_gpu`.
`OLLAMA_N_GPU_LAYERS`	llama.cpp's `n_gpu_layers` with an `OLLAMA_` prefix	Never transferred to Ollama's env layer. Same fix as above.
`OLLAMA_MLX`	Toggle MLX backend on Mac (preview-era assumption)	Not present in current envconfig. Apple Silicon runs on the Metal backend today; no backend switch is exposed. For MLX-native inference, use `mlx-lm` directly.
`OLLAMA_MAX_CONTEXT`	"Hard cap on context length"	Maintainer note: not a current config var. Use `OLLAMA_CONTEXT_LENGTH`.
`OLLAMA_GPU_LAYERS`	Variant naming you'll see in mixed tutorials	Not in the env config. Same fix as `OLLAMA_NUM_GPU`.
`OLLAMA_CACHE_SIZE`	"Limit KV cache memory"	Not in the env config. The current memory knob is `OLLAMA_KV_CACHE_TYPE=q8_0` (quantizes the cache).
`OLLAMA_MEMORY_MODE`	Generic "memory tuning" suggestion in various tutorials	Not in the env config.

Bonus — GGML_METAL_RESIDENCY_KEEP_ALIVE_S (a non-OLLAMA_ env that does land)

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.

Field discovery — GGML_METAL_RESIDENCY_KEEP_ALIVE_S

Origin. Not an Ollama env at all — it belongs to the embedded ggml library that powers Ollama's Metal backend on Apple Silicon. The ggml C code reads it directly via getenv("GGML_METAL_RESIDENCY_KEEP_ALIVE_S"). It controls how long Metal residency-set buffers stay resident after the model is idle.

Why it works without Ollama supporting it. No special passthrough is needed. The chain is plain POSIX:

LaunchAgent (or shell) sets the env on the ollama serve process.
serve spawns model-runner children via fork/exec; children inherit the full env.
Inside the runner, ggml's Metal backend reads the var directly. No Ollama code touches it.

Why you'd care. The default is 180 s. After any idle period longer than that, the residency set is torn down and the next request pays a brutal first-token latency rebuilding it ('처음에만 드럽게 느려' — only the first one is painfully slow). Bumping it to 86400 (24 h) keeps buffers warm across normal idle gaps for an always-on local server.

How to verify it landed. The runner log emits a single line per model load:

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

Why this is in §2 at all. It is the live counter-example to the OSS-convention warning above: not every effective env is in the project's official list, and not every name in the official list is necessarily the only knob that matters. The only way to know what actually took effect is the program's self-report — log lines and startup dumps. That's the §0 lesson, in concrete form: this var is undocumented in any Ollama-side source, learned by log inspection on a production fleet. Future Ollama or ggml releases may rename or retire it; re-verify when in doubt.

§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.

OLLAMA_AUTH
OLLAMA_CONTEXT_LENGTH
OLLAMA_DEBUG
OLLAMA_DEBUG_LOG_REQUESTS
OLLAMA_EDITOR
OLLAMA_FLASH_ATTENTION
OLLAMA_GPU_OVERHEAD
OLLAMA_HOST
OLLAMA_KEEP_ALIVE
OLLAMA_KV_CACHE_TYPE
OLLAMA_LLM_LIBRARY
OLLAMA_LOAD_TIMEOUT
OLLAMA_MAX_LOADED_MODELS
OLLAMA_MAX_QUEUE
OLLAMA_MODELS
OLLAMA_MULTIUSER_CACHE
OLLAMA_NEW_ENGINE
OLLAMA_NOHISTORY
OLLAMA_NOPRUNE
OLLAMA_NO_CLOUD
OLLAMA_NUM_PARALLEL
OLLAMA_ORIGINS
OLLAMA_REMOTES
OLLAMA_SCHED_SPREAD
OLLAMA_VULKAN

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)

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

Available VRAM	Default num_ctx
< 24 GiB	4,096 tokens
24 – 48 GiB	32,768 tokens (32K)
≥ 48 GiB	262,144 tokens (256K)

§5 num_gpu vs OLLAMA_NUM_GPU

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

Where	Name	Scope	Exists?
Server env var	`OLLAMA_NUM_GPU`	Would be a server default	❌ Not in current `envconfig/config.go`. Use the per-request route below.
API request	`options.num_gpu`	Per request	✅ Defined in `api/types.go`.
Modelfile	`PARAMETER num_gpu`	Per model	✅ Valid.

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 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): 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

# Option 1: launchctl setenv (system-wide)
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 — the only ground truth

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.