Ollama is the local LLM runtime: one command downloads and runs open-weight models, with a built-in OpenAI-compatible API (default port 11434), keeping data on your machine. Typical usage: point scripts, agents and IDE plugins at base_url for offline inference, hot model switching and no per-token cost.

Use it when:

• You need local inference: data stays on your machine, works offline, no usage fees;
• You want multiple models in parallel with hot switching;
• You are building a local LLM environment (open-webui as UI, LLaMA-Factory for fine-tuning) — see combo combo-local-llm-finetune;
• You are building a local RAG knowledge base — see combo combo-local-rag (ollama + MaxKB).

Don't use it when: you need cloud-scale capability (very large models / high concurrency / zero maintenance). A local runtime is not a substitute there.

China network reality: both the binary download (GitHub Release, 1.42GB) and model pulls (official registry) can stall. This guide documents two measured workarounds: download the binary via gh-proxy; download models from ModelScope as GGUF and import with ollama create.

One command block for download, extract and verify (measured China path, copy as one block):

# Source: Trove detailed guide · verified 2026-08-29
curl -fsSL -o /tmp/ollama.tar.zst https://gh-proxy.com/https://github.com/ollama/ollama/releases/latest/download/ollama-linux-amd64.tar.zst
tar --zstd -xf /tmp/ollama.tar.zst -C /usr/local
ollama --version

Expected output: ollama version 0.33.2 (measured 2026-08-29)

Seeing the version means install succeeded. Three notes:

1. tar --zstd needs zstd (apt-get install -y zstd, measured zstd 1.5.7);
2. It is a 1.42GB download: check disk first (df -h /), resume with curl -C - if interrupted;
3. Windows: recommended path is WSL2 (same as Linux); native Windows installer also exists; macOS uses the official dmg.

Confirm:

• ollama --version prints ollama version 0.33.2;
• ollama list runs (empty model table, exit 0).

Install variants (deep dive)

Ollama is single-binary + model directory. ollama serve starts a resident service (listening on 127.0.0.1:11434 by default), ollama pull <model> downloads models from the official registry into the model dir, ollama run <model> runs interactively, ollama create imports a model from a GGUF file. NVIDIA GPUs enable CUDA automatically; without a GPU it falls back to CPU inference (usable but slow).

Two key mechanisms:

• OLLAMA_MODELS env var: model directory (default ~/.ollama/models). Models are 4~70GB each; point it at a large partition when the system disk is tight — isolated test passed 2026-08-30 (local repro log 2026-08-30).
• GGUF import: ollama create <name> -f Modelfile imports a local GGUF file into the model library, bypassing the official registry — the correct fix for China model pulls (measured 2026-08-29: qwen2.5-0.5b-instruct-q4_k_m 491MB download in 58.5s + create success + CPU smoke pass, local repro log 2026-08-29).

Write surface: model dir ~/.ollama/models (or OLLAMA_MODELS target) + ~/.ollama/id_ed25519 (SSH key generated on first serve, observed in serve logs). Service listens on 127.0.0.1:11434 by default, not exposed externally.

Connecting from containers: bridge-network containers reach host Ollama at 172.17.0.1:11434, but snap/apt Ollama on Linux listens on 127.0.0.1 only — containers cannot reach it without sudo snap set ollama host=0.0.0.0:11434 + restart (measured pitfall in combo-local-rag).

Step 1: start the service (serve)

Why this step: Ollama is a resident service; all API calls go through it. Without serve, curl /api/version fails.

# Source: Trove detailed guide · verified 2026-08-29
OLLAMA_MODELS=~/.ollama/models ollama serve

Expected output: normal server config logs (ssh key generated, blobs: 0; default port 11434; measured 2026-08-29)

# Source: Trove detailed guide · verified 2026-08-29
curl -s http://127.0.0.1:11434/api/version

Expected output: {"version":"0.33.2"} (measured 2026-08-29)

If stuck:

• serve won't start / port busy → change OLLAMA_HOST (e.g. OLLAMA_HOST=127.0.0.1:11435);
• unreachable from a container → use 172.17.0.1:11434; snap Ollama needs sudo snap set ollama host=0.0.0.0:11434 + restart listener (see "Why it works this way").

Step 2: import your first model (China fix)

Why GGUF: ollama pull uses the official registry, which times out in China (serve logs show cloud model cache fetch failure on ollama.com:443). ModelScope is reachable in China; download GGUF and import.

# Source: Trove detailed guide · verified 2026-08-29
# 1) Download GGUF from ModelScope (example: qwen2.5-0.5b-instruct Q4_K_M, 491MB)
pip install modelscope -i https://pypi.tuna.tsinghua.edu.cn/simple
modelscope download --model Qwen/Qwen2.5-0.5B-Instruct-GGUF qwen2.5-0.5b-instruct-q4_k_m.gguf --local_dir /tmp/qwen-gguf
# 2) Write Modelfile
echo "FROM /tmp/qwen-gguf/qwen2.5-0.5b-instruct-q4_k_m.gguf" > /tmp/Modelfile
# 3) Import
ollama create qwen2.5:0.5b -f /tmp/Modelfile

Expected output: create prints model manifest summary + success (measured 2026-08-29: 491MB download 58.5s + create success + CPU smoke pass)

# Source: Trove detailed guide · verified 2026-08-29
ollama run qwen2.5:0.5b "Hello"

Expected output: normal model reply (CPU smoke, measured 2026-08-29)

If stuck:

• modelscope download slow → retry with an alternative China mirror; GGUF has multiple quant levels (q4_k_m is a size/quality balance);
• create errors → check the Modelfile FROM path points at the actual downloaded .gguf file;
• run gives no output → confirm serve is running and the model was created (ollama list shows it).

Step 3: daily usage

# Source: Trove detailed guide · verified 2026-08-29
ollama list                          # installed models
ollama ps                            # currently loaded models
ollama rm <model>                    # delete a model to free disk (measured, see models-rm-v3)
curl -s http://127.0.0.1:11434/api/version   # service health check

Expected output: list prints a model table (NAME/ID/SIZE/MODIFIED); ps prints loaded models and VRAM; rm removes it from list; version returns {"version":"0.33.2"}

Move the model directory (when the system disk is tight):

# Source: Trove detailed guide · verified 2026-08-29
mkdir -p /data/ollama/models
OLLAMA_MODELS=/data/ollama/models ollama serve

Expected output: serve initializes the new directory (blobs: 0; isolated test passed 2026-08-30, evidence）

If stuck:

• old models invisible after migration → models are stored per directory; after switching dirs you need to pull/create again; copy the whole original directory when migrating;
• rm does not free space → confirm the model is not loaded (run ollama stop or wait for inference to finish before rm).

Same source as the tool-page matrix; full pairs, states and evidence on the conflict matrix. Known relations:

• open-webui × ollama = compatible (verified): full-chain test during open-webui inclusion 2026-09-01 (open-webui container talking to host ollama, inference OK);
• MaxKB × ollama = compatible (verified): combo-local-rag test 2026-09-01 (container via 172.17.0.1 + open-book Q&A hitting knowledge-base facts);
• LLaMA-Factory / other CLI tools: non-overlapping write surfaces (own dirs), static judgment: can coexist.

• Symptom: ollama pull spins/times out → official registry unreachable in China; use ModelScope GGUF + create (see section 5 step 2)
• Symptom: container curl 172.17.0.1:11434 connection refused → snap build listens on 127.0.0.1 only; sudo snap set ollama host=0.0.0.0:11434 + restart listener
• Symptom: tar: unrecognized option --zstd → apt-get install -y zstd first (measured zstd 1.5.7)
• Symptom: serve log cloud model cache fetch failure (ollama.com:443) → normal sign that the official registry is unreachable; use the GGUF import path
• Symptom: model dir out of space → point OLLAMA_MODELS at a large partition (migration measured 2026-08-30)
• Symptom: port 11434 busy → OLLAMA_HOST=127.0.0.1:11435

Full four-section entries (symptom→cause→fix→evidence): site docs

# Source: Trove detailed guide · verified 2026-08-29
ollama stop 2>/dev/null || true
rm -rf /usr/local/lib/ollama /usr/local/bin/ollama /usr/local/bin/ollama-app 2>/dev/null || true
rm -rf ~/.ollama

Expected output: commands exit cleanly; ollama --version says command not found; ~/.ollama gone

Note: ~/.ollama holds all models (tens of GB); confirm you don't need them before deleting. If OLLAMA_MODELS points elsewhere, deleting ~/.ollama does not clean the new location — handle both.

• Q: Why does pull always time out? A: the official registry (ollama.com:443) times out on direct China connections (measured). The established path is ModelScope GGUF + ollama create (measured 2026-08-29: 491MB/58.5s download + import OK). Don't keep retrying pull.
• Q: Where are models stored and how big? A: ~/.ollama/models (default); single models 4~70GB; use OLLAMA_MODELS for a large partition (migration measured 2026-08-30).
• Q: Can I install several models at once? A: Yes. Multiple pulls/creates don't interfere; ollama run <name> selects; ollama ps shows what is loaded.
• Q: How do open-webui/MaxKB connect to ollama? A: OpenAI-compatible: set base_url=http://172.17.0.1:11434 (container) or http://127.0.0.1:11434 (host). If the container cannot connect, check the snap host setting (section 5).
• Q: Does it work without an NVIDIA GPU? A: Yes, CPU fallback (usable but slow); 0.5B smoke is fine, large models need a GPU (RTX 5070 Ti measured in this environment).
• Q: Where do I report issues? A: install/uninstall issues go through this entry's feedback; project issues go to the author repo.

• Version: 0.33.2 (manifest locked; measured 2026-08-29).
• Environment: Linux x86_64 (WSL2 Ubuntu measured); Windows via WSL2 or official installer; macOS official dmg.
• Network: GitHub Release via gh-proxy (measured); models via ModelScope GGUF import (measured); official registry direct times out (measured).
• Write surface: ~/.ollama/ (model dir + id_ed25519); OLLAMA_MODELS migrates it.
• Port: 11434 (OLLAMA_HOST overridable); container interop via 172.17.0.1.

• Sources: official project docs (English README/docs) + local measurements (2026-08-29/30)
• Entry signature: ollama/ollama (MIT, kept as 0.33.2)

• Measured: local repro log 2026-08-29 (gh-proxy 1.42GB download + version smoke); local repro log 2026-08-29 (ModelScope GGUF import flow); local repro log 2026-08-30 (model dir migration); local repro log 2026-08-30 (rm frees disk); local repro log 2026-08-30 (local RAG chain, combo-local-rag boost); local repro log (service startup logs)
• Not tested: Windows installer / macOS dmg / AMD ROCm (no such environment; honestly marked)

Third-party tutorials are not individually verified; check against this page and official docs.

• 官方文档层（docs.ollama.com，v0.33.2）：Ollama 完整用法 [官方文档 · Ollama 官方 · 2026-08-31（guide 收录版本 0.33.2）]
  官方用法全解——安装（Linux/macOS/Windows）、ollama serve/pull/run 核心命令、模型管理（OLLAMA_MODELS 目录、模型拉取）、OpenAI 兼容 API、GGUF 模型导入、多模型并行与热切换