Ollama 환경 변수 — 필드 가이드

빠르게 움직이는 OSS 프로젝트의 version drift를 따라잡는 현장 레퍼런스

Ollama v0.20.7 (2026-04-17) 기준 검증. Ollama는 릴리스 사이에 환경 변수를 rename하고 remove하고 조용히 드롭해. OLLAMA_NUM_CTX, OLLAMA_NUM_GPU, OLLAMA_MLX 같은 이름들은 옛날 버전에선 멀쩡히 동작했지만 지금 서버는 그냥 무시해 — deprecation 경고도 없고, 로그 라인도 없어. 이 가이드는 지금 이 순간 인식되는 게 뭔지에 대한 스냅샷이야. 그리고 시간 따라가려면 어떤 습관이 필요한지에 대한 얘기야.

§0 OSS 컨벤션 — 모든 OSS 문서에 적용되는 읽기 순서

이 페이지의 어떤 구체적 사실보다 먼저 익혀야 하는 메타 룰: 오픈 소스 문서는, 이 페이지 포함, 무조건 stale 돼. 그건 결함이 아니라 컨벤션이야.

OSS 계약을 평범한 말로

코드가 먼저 나가고, 문서는 뒤늦게 — 또는 영영 안 따라가. 메인테이너는 기능, 수정, 리팩터를 먼저 챙겨. README 업데이트, 블로그 포스트, 튜토리얼은 코드보다 몇 주, 몇 달, 또는 영원히 늦어.
Rename, removal, 조용한 breakage가 일상이야. 아무도 아빠 옛날 config를 동작 상태로 유지해줄 의무가 없어. Deprecation 경고는 호의지, 보장이 아니야.
튜토리얼은 타임캡슐이야. 지난 분기 블로그 포스트가 틀린 게 아니야 — 쓴 그날엔 맞았어. 프로젝트가 움직였고, 포스트는 안 움직인 거야.
맨손으로 부딪히는 건 입장료야. 문서대로 안 되면 source, issue, 최근 commit, 시작 로그를 — 이 순서로 — 본다. OSS의 기본 철학이지 벌이 아니야.

이 가이드 날짜는 2026-04-17, Ollama v0.20.7이야. 아래 모든 주장은 "그 날짜, 그 빌드에선 사실"로 받아들여 — 영원한 경전이 아니야. 몇 달 뒤 뭔가 안 되면, 가장 먼저 할 일은 이 페이지가 거짓말한다고 가정하는 게 아니라 ollama serve 찍어서 dump 보고 envconfig/config.go의 최근 commit 보는 거야.

§1 TL;DR — 의미가 빠져나간 다섯 이름

블로그 포스트, Stack Overflow 답변, AI 어시스턴트 출력에서 본 Ollama 튜닝 변수들 중 몇 개는 옛날 버전에선 진짜 설정이었어. 근데 지금 서버 (v0.20.7)는 안 읽어. 프로젝트가 진화하면서 rename됐거나, 대체됐거나, 조용히 제거된 거. 그리고 Ollama는 만났을 때 deprecation 경고를 안 띄워.

이름 (더 이상 인식 안 됨)	옛날에 했던 일 / 의도	v0.20.7에서 동작하는 것
`OLLAMA_NUM_CTX`	서버 전역 context length	`OLLAMA_CONTEXT_LENGTH` (env) 또는 `options.num_ctx` (요청별)
`OLLAMA_NUM_GPU`	서버 레벨에서 모든 layer를 GPU로 강제	요청별 `options.num_gpu` 또는 Modelfile `PARAMETER num_gpu` (discrete GPU 한정)
`OLLAMA_N_GPU_LAYERS`	llama.cpp 스타일 layer offload	위와 동일
`OLLAMA_MLX`	Apple Silicon에서 MLX backend 토글 (preview 시절)	현재 envconfig에 없음. Apple Silicon은 Metal backend로 ship; MLX-native 추론은 `mlx-lm`을 직접 돌려.
`OLLAMA_MAX_CONTEXT`	서버 context 상한	`OLLAMA_CONTEXT_LENGTH`

§2 Ghost Variables — 빠져나간 이름들

이 이름들은 많은 튜토리얼, 스크린샷, AI가 만든 config에 등장해. Ollama 역사 어느 시점에선 유효했거나 (또는 합리적 유추로 llama.cpp에서 가져온 거), 지금 서버는 안 읽어. Deprecation 경고도, 로그 라인도 없어 — 그냥 무력해.

이름	왜 사람들이 설정하는지	v0.20.7 상태 / 오늘 쓸 것
`OLLAMA_NUM_CTX`	"기본 context window 설정"	Rename. Issue #14130 메인테이너 노트가 현재 config var 아님을 확인. `OLLAMA_CONTEXT_LENGTH` 사용.
`OLLAMA_NUM_GPU`	"서버 레벨에서 모든 layer를 GPU로 강제"	현재 envconfig에 없음. Layer count knob은 요청 시점에 살아 있음: API `options.num_gpu` 또는 Modelfile `PARAMETER num_gpu`.
`OLLAMA_N_GPU_LAYERS`	llama.cpp의 `n_gpu_layers`에 `OLLAMA_` prefix 붙인 형태	Ollama env layer로 옮겨진 적 없음. 위와 동일한 fix.
`OLLAMA_MLX`	Mac에서 MLX backend 토글 (preview 시절 가정)	현재 envconfig에 없음. Apple Silicon은 오늘 Metal backend로 동작; backend switch는 노출 안 됨. MLX-native 추론은 `mlx-lm` 직접 사용.
`OLLAMA_MAX_CONTEXT`	"context length 하드 캡"	메인테이너 노트: 현재 config var 아님. `OLLAMA_CONTEXT_LENGTH` 사용.
`OLLAMA_GPU_LAYERS`	섞인 튜토리얼에서 보이는 변형 명명	Env config에 없음. `OLLAMA_NUM_GPU`와 동일한 fix.
`OLLAMA_CACHE_SIZE`	"KV cache 메모리 제한"	Env config에 없음. 현재 메모리 knob은 `OLLAMA_KV_CACHE_TYPE=q8_0` (cache 양자화).
`OLLAMA_MEMORY_MODE`	여러 튜토리얼의 일반적 "메모리 튜닝" 제안	Env config에 없음.

보너스 — GGML_METAL_RESIDENCY_KEEP_ALIVE_S (OLLAMA_ 안 붙은 env가 동작하는 케이스)

Ghost vars는 서버가 안 읽는 OLLAMA_* prefix 이름들이야. 그 거울상이 더 흥미로워: OLLAMA_* prefix 없는데도 일반 POSIX 상속 덕분에 효과가 살아있는 env — 그리고 어떤 공식 Ollama 문서에도 언급 없음.

현장 발견 — GGML_METAL_RESIDENCY_KEEP_ALIVE_S

출처. Ollama env가 아니야 — Ollama의 Apple Silicon Metal backend를 떠받치는 임베디드 ggml 라이브러리 소속이야. ggml의 C 코드가 getenv("GGML_METAL_RESIDENCY_KEEP_ALIVE_S")로 직접 읽어. 모델 idle 후 Metal residency-set 버퍼가 얼마나 오래 resident로 남는지 제어해.

왜 Ollama가 'support' 안 해도 동작하는지. 특별한 passthrough 필요 없음. 체인은 평범한 POSIX:

LaunchAgent (또는 shell)이 ollama serve 프로세스에 env 설정.
serve는 fork/exec로 model-runner child를 spawn; child는 전체 env를 상속.
Runner 안에서 ggml의 Metal backend가 변수를 직접 읽어. Ollama 코드는 건드리지 않음.

왜 신경 써야 하는지. 디폴트는 180 s야. 그보다 긴 idle 후엔 residency set이 해제되고, 다음 요청은 그걸 다시 쌓느라 first-token latency가 처참해 ('처음에만 드럽게 느려' — '오직 첫 번째만 고통스럽게 느림'). 86400 (24h)으로 올리면 always-on 로컬 서버에서 일반적인 idle gap을 가로질러 버퍼가 따뜻하게 유지돼.

제대로 들어갔는지 검증하는 법. Runner 로그가 모델 로드마다 단 한 줄을 뱉어:

grep -m1 'residency set collection' ~/Library/Logs/ollama.log
# env 설정 시:   ... (keep_alive = 86400 s)
# 디폴트 (env 없을 때):  ... (keep_alive = 180 s)

왜 §2에 있냐면. 위 OSS-컨벤션 경고에 대한 살아있는 반례야: 효과 있는 모든 env가 프로젝트의 'official' 리스트에 있는 건 아니고, official 리스트에 있는 모든 이름이 유일하게 중요한 knob도 아니야. 실제 효과 있는 게 뭔지 아는 유일한 방법은 프로그램의 자기 보고 — 로그 라인과 시작 dump뿐. 그게 §0 교훈을 구체로 옮긴 거야: 이 변수는 Ollama 쪽 어떤 소스에도 문서화 안 됨, 프로덕션 fleet의 로그 인스펙션으로 학습됨. 미래 Ollama나 ggml 릴리스가 rename / retire할 수 있으니 의심되면 재검증.

§3 공식 25개 변수

Ollama v0.20.7의 envconfig/config.go에서 추출. 서버가 실제 파싱하는 OLLAMA_* env vars는 이게 전부.

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

위에 안 나오는 OLLAMA_ prefix 다른 이름은 이 버전이 안 읽는 거야. 좋은 소식: 프로덕션에서 손이 가는 이름들은 다 여기 있어 — flash attention, KV cache type, keep-alive, host, parallel requests, max loaded models.

이 리스트는 v0.20.7 스냅샷이야. 미래 릴리스는 추가하고 제거해. 어떤 문서도 — 이 페이지 포함 — 무한히 믿지 말고, 로컬 ollama serve 시작 dump에 대조해서 재검증해.

§4 Context Length — 3-Tier 우선순위

가장 오해받는 Ollama 설정이야. v0.15.5+부터, 서버는 3-tier 우선순위 체인으로 context length를 골라. 이걸 이해하면 'context가 왜 이상해?' 혼란의 90%가 사라져.

3 tier (높은 우선순위가 이김)

API 요청 — 요청 body의 options.num_ctx. 아래 모두를 이김.
서버 env var — 서버 시작 시 OLLAMA_CONTEXT_LENGTH. VRAM auto를 이김.
VRAM auto-detect — 가용 VRAM 기반 서버 디폴트.

가용 VRAM	디폴트 num_ctx
< 24 GiB	4,096 토큰
24 – 48 GiB	32,768 토큰 (32K)
≥ 48 GiB	262,144 토큰 (256K)

§5 num_gpu vs OLLAMA_NUM_GPU

이름 충돌이 끝없는 혼란을 만들어. 전체 그림:

위치	이름	스코프	존재?
서버 env var	`OLLAMA_NUM_GPU`	서버 디폴트가 됐을 것	❌ 현재 `envconfig/config.go`에 없음. 아래 요청별 경로 사용.
API 요청	`options.num_gpu`	요청별	✅ `api/types.go`에 정의.
Modelfile	`PARAMETER num_gpu`	모델별	✅ 유효.

실제로 뭘 하는 건지

Discrete-GPU 시스템 (NVIDIA / AMD)에서 num_gpu는 모델 layer를 GPU에 몇 개 offload할지 제어해. 999로 두면 Ollama가 모든 layer를 GPU에 (또는 들어가는 만큼) 올려. 낮추면 layer가 시스템 RAM으로 밀려나.

요청별 예제 (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,        # 모든 layer를 GPU로
        "num_ctx": 8192,       # 이 요청 한정 context
    },
})

§6 Outdated Tutorials, 업데이트

아래 각각은 Ollama 역사 어느 시점엔 좋은 조언이었어. 프로젝트가 움직였고, 조언은 안 움직였어. 누구 잘못도 아니야 — stale 된 스냅샷일 뿐.

§7 macOS 서버 정확한 Config

A. shell에서 Homebrew ollama serve

export OLLAMA_HOST=0.0.0.0:11434
export OLLAMA_CONTEXT_LENGTH=131072      # 명시적 128K (생략 시 VRAM-auto)
export OLLAMA_FLASH_ATTENTION=1
export OLLAMA_KV_CACHE_TYPE=q8_0
export OLLAMA_KEEP_ALIVE=-1              # 절대 unload 안 함
export OLLAMA_NUM_PARALLEL=2             # 동시 요청 수
export OLLAMA_MAX_LOADED_MODELS=3

# Bonus (Apple Silicon, §2 보너스 참고): OLLAMA_* var 아니지만
# fork/exec로 Metal runner에 상속됨. 디폴트 180s는 idle 후 첫
# 토큰 latency 처참함. 86400 = 24h 동안 버퍼 따뜻하게.
export GGML_METAL_RESIDENCY_KEEP_ALIVE_S=86400

ollama serve

B. LaunchAgent plist (로그인 시 auto-start)

<key>EnvironmentVariables</key>
<dict>
  <key>OLLAMA_HOST</key>                          <string>0.0.0.0:11434</string>
  <key>OLLAMA_CONTEXT_LENGTH</key>                <string>131072</string>  <!-- 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 보너스) -->
</dict>

C. Ollama.app GUI gotcha

# 옵션 1: launchctl setenv (시스템 전역)
launchctl setenv OLLAMA_CONTEXT_LENGTH 131072
launchctl setenv OLLAMA_FLASH_ATTENTION 1
launchctl setenv OLLAMA_KV_CACHE_TYPE q8_0

# 그 다음 Ollama.app 종료하고 재실행

옵션 2: 최근 Ollama.app 빌드 안의 Settings UI 사용 — context-length 슬라이더와 성능 토글 몇 개 있음.

§8 Config 검증 — 유일한 ground truth

Ollama는 인식하는 모든 config를 서버 시작 시 dump해. 이게 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 \
       …]"

디폴트 빠르게 확인하는 한 줄

# 서버 재시작, 첫 50줄 캡처
ollama serve 2>&1 | head -n 50 | grep -E "server config|total_vram|default_num_ctx"

한 번에 env var와 VRAM 기반 자동 감지 context 디폴트 둘 다 보여.

보너스: ggml-layer env 검증 (§2 보너스)

map[…] dump는 OLLAMA_* var만 커버해. GGML_METAL_RESIDENCY_KEEP_ALIVE_S 같은 non-Ollama env가 runner에 닿았는지 확인하려면 두 군데 봐:

# 1. 라이브 서버 프로세스에 env가 있는지?
ps eww $(pgrep -f 'ollama serve' | head -1) | tr ' ' '\n' | grep -E 'OLLAMA_|GGML_'

# 2. Runner가 모델 로드 시 실제 사용했는지?
grep -m1 'residency set collection' ~/Library/Logs/ollama.log
# 기대: ... (keep_alive = 86400 s)
# 디폴트:  ... (keep_alive = 180 s)

같은 원리가 일반화돼: Ollama가 링크하는 라이브러리 (ggml, Metal, CUDA)에서 온 env는 Ollama 자기 시작 dump에 안 나오지만 표준 POSIX fork/exec 상속으로 효과는 살아있을 수 있어. 라이브 프로세스에 ps eww 그리고 runner 자기 로그 라인이 확인할 유일한 방법이야.

§9 Sources

envconfig/config.go — 인식되는 env vars의 결정적 리스트
api/types.go — API 요청 옵션의 결정적 리스트 (num_ctx, num_gpu 등)
Issue #14130 — OLLAMA_NUM_GPU/OLLAMA_NUM_CTX/OLLAMA_MAX_CONTEXT가 config 변수 아님을 메인테이너가 확인
PR #8938 — OLLAMA_CONTEXT_LENGTH 도입 (2025년 2월)
docs.ollama.com/faq
docs.ollama.com/context-length
ggml-org/ggml — Metal backend를 소유하고 GGML_METAL_RESIDENCY_KEEP_ALIVE_S를 직접 읽는 임베디드 라이브러리
현장 발견 (§2 보너스) — GGML_METAL_RESIDENCY_KEEP_ALIVE_S 동작은 프로덕션 Apple Silicon fleet (Mac Studio M3 Ultra)의 runner 로그 인스펙션으로 학습됨. v0.20.7 기준 어떤 Ollama 쪽 소스에도 문서화 안 됨. 미래 릴리스에서 재검증.