简介：面向需要在 Linux/macOS 等类 Unix 系统上快速部署 Ollama 的开发者、运维人员与 AI 应用爱好者，这份安装部署指引包帮助用户打通从安装包获取、系统环境准备到最终配置验证的完整链路。压缩包仅 3 个文件，包含 shell 自动安装脚本、PHP 服务端脚本与 txt 说明文档；shell 脚本覆盖依赖检查、权限设置及安装执行等步骤，PHP 脚本可在 Web 环境下触发下载或生成安装包，说明文档则集中梳理系统要求、安装要点与常见问题。整个资源包大小仅 13KB，轻量易用，目前已有 434 人学习使用。通过这套资源，读者既能理解 Ollama 部署的标准化流程，也能掌握 Shell 脚本自动化安装的常见写法；安装中遇到环境依赖或权限异常时，可依据说明文档快速定位并修复。对于初次接触大模型工具链的入门者，这是一份友好的实操指南；对于有经验的工程师，也可作为部署检查清单或内部培训参考。 Ollama 安装这件事，真没有表面看起来那么简单。很多人以为就是下载安装包、双击、下一步，结果要么卡在下载进度条上，要么装完后被模型下载再折磨一轮，最后 C 盘还红了。这篇把 Ollama 从安装、模型管理、报错排查到生态对接的完整链路梳理一遍，目标是让"在自己电脑上跑起本地大模型"变成一条可以照着做的操作路径。适合刚接触本地模型的小白，也适合准备在开发机或服务器上部署 Ollama 的工程人员。

1. 别把安装当成"下一步到底"：先搞清楚 Ollama 到底装了什么

1.1 一个安装包背后的四个组件

Ollama 的安装包并不是一个简单的命令行工具，它实际上由四部分组成：

• CLI 客户端：也就是你在终端里敲 ollama run 用的命令；
• 常驻服务：Windows 上是托盘后台程序，Linux 上是 systemd 服务，负责管理模型生命周期和对外 API；
• 推理引擎：基于 llama.cpp 等底层能力封装，负责真正跑模型推理；
• 模型存储目录：默认在 C:\Users\用户名\.ollama\models （Windows）或 ~/.ollama/models （Linux/macOS）。

很多人踩坑，是因为没搞明白最后一点：模型文件根本不放在安装目录里，而是单独放在用户目录下。这就解释了两个高频问题——为什么装完 Ollama 但 C 盘还在持续变大；为什么你明明把安装包装到了 D 盘，模型还是在 C 盘。

安装过程中 Ollama 会注册一个本地 HTTP 服务，端口默认是 11434。所有客户端工具（Cherry Studio、Open WebUI、Codex 等）本质上都是往 http://127.0.0.1:11434 发请求。把这一点记在心里，后面排查问题会轻松很多。

1.2 下载慢、卡死的根源并不在安装包本身

Ollama 官方安装包托管在 GitHub Releases 上，模型仓库在海外服务器，这两个环节在部分地区访问都不稳定。安装包只有几百 MB，卡一下还能忍；模型动辄几个 GB，那才是真正的考验。

另外提一句：Ollama 官方不支持 Windows 7，老机器就不要再折腾原版安装了，要么升级系统，要么用 Docker 之类的方案，强行装旧版反而会引入一堆兼容性问题。

2. 从下载到运行：各平台安装实操与"装到 D 盘"完整方案

2.1 Windows 安装：新版选目录，旧版做迁移

Windows 安装包是 OllamaSetup.exe ，双击后新版安装向导已经支持自定义安装位置。如果用的是新版本，安装时直接把路径改成 D:\Ollama 就行。

但更多人遇到的场景是：早期版本装完了才发现全在 C 盘，或者安装向导根本没有给出选项。这时候需要手动迁移程序目录：

1. 右键托盘图标退出 Ollama，确保进程完全结束；
2. 把整个 C:\Users\用户名\AppData\Local\Programs\Ollama 文件夹移动到 D:\Ollama ；
3. 打开管理员命令行，执行：

   mklink /J "C:\Users\用户名\AppData\Local\Programs\Ollama" "D:\Ollama"
   

   这个命令创建的是目录联接（junction），对系统来说效果和原目录一样，但实际文件已经存在 D 盘；
4. 重新启动 Ollama，运行 ollama --version 验证。

注意：迁移程序目录时一定要先退出托盘进程，否则文件被占用会迁移失败。创建目录联接后不要再去动 C 盘那个链接，否则程序会直接失效。

2.2 模型目录固定到 D 盘，别再让 C 盘变红

程序目录迁移只是第一步。模型默认下载到 C:\Users\用户名\.ollama\models ，不处理的话，C 盘照样会爆。正确做法是通过环境变量 OLLAMA_MODELS 指定新的模型存储位置：

1. 在系统环境变量里新增用户变量，变量名 OLLAMA_MODELS ，值设为 D:\ollama\models ；
2. 完全退出 Ollama（托盘右键 Quit），再重新启动；
3. 打开终端输入 ollama list ，如果之前下过模型但列表变空了，说明环境变量没生效或者路径不对；
4. 把旧目录下的模型文件移动过去，注意 OLLAMA_MODELS 路径下的结构要和原来 \.ollama\models\ 保持一致。

我实测下来的结果：模型文件迁移完成后再跑 ollama list ，已下载模型会正确识别，不用重新下载。这也是最省流量的做法。

2.3 macOS 和 Linux 的命令行安装

macOS 可以直接下载官方 dmg，也可以走命令行。Linux 服务器上最常用的是官方一键脚本：

curl -fsSL https://ollama.com/install.sh | sh

安装完成后用 systemctl status ollama 检查服务状态，如果没起来就手动启动：

sudo systemctl start ollama
sudo systemctl enable ollama

如果是以 root 用户跑的，留意一下当前用户是否有模型目录的读写权限。很多 Linux 上报错 permission denied ，就是因为 Ollama 服务使用的是独立用户，而模型目录建在 root 家目录下。

2.4 安装包下载太慢，别反复重试

官方安装包下载慢，我的建议是不要在一个下载源上反复重试，越重试越容易断。可以找可信的 GitHub Release 加速服务，或者去国内模型社区找热心用户搬运的安装包。拿到安装包后先看文件体积是否和官方一致，运行前最好核对一下 SHA256 校验值，防止来路不明的文件混进去。

3. 模型拉取卡住不等于坏了：离线导入是最稳的路线

3.1 ollama pull 到底在干什么

ollama pull qwen2.5 这条命令会从远程仓库拉取模型的 manifest 和若干层文件，存到 OLLAMA_MODELS 目录。模型体积大、网络不稳定，pull 很容易卡在某个百分比不动。

很多人以为卡住就是安装坏了，直接 Ctrl+C，然后重试，接着再卡。实际上可以换个思路：不依赖官方仓库，直接在国内模型社区下载 GGUF 格式的模型文件，通过本地导入的方式“绕过”下载环节。

3.2 从 ModelScope 下载 GGUF 并导入 Ollama

以 Qwen2.5 7B Instruct 为例，完整步骤如下：

1. 打开国内模型社区（ModelScope 等平台），搜索 qwen2.5-7b-instruct-gguf ；
2. 下载量化版文件，推荐 q4_K_M 后缀的 GGUF 文件，体积大约 4.7GB；
3. 下载完成后，新建一个文本文件，命名为 Modelfile ，内容写：

   FROM ./qwen2.5-7b-instruct-q4_k_m.gguf
   

   如果需要调整上下文长度，可以追加：

   PARAMETER num_ctx 8192
   

4. 在 Modelfile 所在目录执行：

   ollama create qwen2.5-local -f Modelfile
   

5. 运行验证：

   ollama run qwen2.5-local
   

导入完成后， qwen2.5-local 就是一个和官方 pull 下来几乎一样的本地模型，可以正常用 API 调用。

3.3 选模型先算内存和显存

很多人在第一步就选错了模型。7B 模型听起来不大，但跑起来很吃内存。我的建议是：

• 8GB 内存的机器，老老实实用 3B/4B 模型（比如 qwen2.5:3b）；
• 16GB 内存可跑 7B 的 q4_K_M 量化版，别碰 14B；
• 32GB 以上再考虑 14B 或更大模型。

量化等级同样关键。q4_K_M 是速度和质量的平衡点，除非显存充裕，否则不建议上 q8_0。模型加载到内存里还涉及 KV Cache，上下文越长占用越高，所以内存余量要留足，别看着模型文件大小是 4.7GB 就以为 8GB 内存够用。

4. 更工程化的部署：WSL2 与 Docker 两条路线

4.1 WSL2 安装慢、报 403 的处理

在 Windows 上通过 WSL2 跑 Ollama，好处是环境干净、和 Linux 服务器行为一致，但 WSL 本身的安装就是个坎。 wsl --install 卡住不动，或者提示 403，通常是下载发行版镜像超时。

我的处理习惯：

1. 先启用必要功能，执行 wsl --install --no-distribution ，或者手动开启“适用于 Linux 的 Windows 子系统”和“虚拟机平台”；
2. 重启后不要直接 wsl --install -d Ubuntu-24.04 ，先 wsl --update 更新内核；
3. 如果还是下载超时，从官方渠道手动下载 Ubuntu 的 appx 离线包，用 Add-AppxPackage 命令安装；
4. 安装完成用 wsl --set-default-version 2 确保走 WSL2。

在 WSL2 里装 Ollama 直接用 Linux 脚本，模型目录会落在 Linux 的 ext4 文件系统里。这里有个关键提醒：不要把模型目录放到 /mnt/c 下面，虽然能访问 Windows 文件，但跨文件系统读写性能损失惨重，加载模型会慢到怀疑人生。

4.2 Docker 部署：一条命令拉起服务化环境

如果你已经有 Docker 环境，Ollama 官方镜像是最省心的部署方式：

docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama

容器跑起来后，在宿主机直接访问 http://127.0.0.1:11434 就能用。要进入容器拉模型：

docker exec -it ollama ollama pull qwen2.5

NVIDIA GPU 用户需要额外安装 nvidia-container-toolkit ，然后加上 --gpus all 参数。没有 GPU 也能跑，纯 CPU 推理就是慢一些，小模型日常用没问题。

4.3 三条路线怎么选

Windows 原生适合绝大多数学桌面工具、接聊天 UI 的用户；Docker 适合开发环境、想一键重装、或者需要快速迁移服务的场景；WSL2 适合本来就在 Linux 环境里开发、想和宿主机共享代码和工具链的人。别三条都折腾一遍，选一条跑通就行。

5. 装完先做这三件事：模型管理、API 自测、高频报错排查

5.1 模型管理的常用命令

ollama list          # 查看本地已有哪些模型
ollama pull 模型名    # 下载模型
ollama run 模型名     # 运行并进入交互对话
ollama ps            # 查看当前哪些模型被加载到内存
ollama rm 模型名      # 删除模型
ollama show 模型名    # 查看模型详情

其中 ollama ps 容易被忽略，但它能即时反映模型占用内存情况。如果机器变卡，先看是不是有模型一直驻留内存，通过 ollama stop 卸载。

5.2 用 curl 验证 API，再接任何客户端

在接入 Cherry Studio、Claude Code 这些工具之前，先在终端把 API 跑通：

curl http://127.0.0.1:11434/api/generate -d '{
  "model": "qwen2.5-local",
  "prompt": "你好，用一句话介绍你自己",
  "stream": false
}'

OpenAI 兼容接口也一样可以测：

curl http://127.0.0.1:11434/v1/chat/completions -d '{
  "model": "qwen2.5-local",
  "messages": [{"role": "user", "content": "你好"}]
}'

如果要在局域网内让其他机器访问，设置环境变量 OLLAMA_HOST=0.0.0.0 ，重启服务。需要跨域调用时再设置 OLLAMA_ORIGINS=* 。

5.3 高频报错排查表

报错现象	常见原因	处理方式
pull model manifest: file does not exist	模型名写错或不存在	去官网查准确的模型名
拉取模型长时间卡住	网络不稳定	停止后换离线导入方案
llama runner 启动失败	内存不足或量化等级太高	换更小模型，检查内存余量
端口 11434 被占用	已有实例在跑	换 OLLAMA_HOST 指定其他端口
OLLAMA_MODELS 设置了但没生效	服务未完全重启	托盘彻底退出，任务管理器确认进程结束
ComfyUI 提示 pip install 缺失节点	那是 ComfyUI 的 Python 依赖问题	和 Ollama 无关，先解决虚拟环境依赖

最后那一条要单独说：最近在 ComfyUI 社区常看到“请先在你的 python 环境中运行 pip install -u --pre comfyui-manager”这类报错，这和 Ollama 安装没什么关系，是节点管理器依赖缺失。别把它们混在一起排查，否则会白白浪费好几个小时。

6. 把本地模型接进常用工具：Cherry Studio、Claude Code、Codex 实战

6.1 万能公式：OpenAI 兼容接口

Ollama 从某个版本开始提供 /v1 接口，协议兼容 OpenAI。这意味着任何支持自定义 OpenAI API 地址的客户端，都可以通过同一套配置接入：

• Base URL： http://127.0.0.1:11434/v1
• API Key：随便填一长串字符，比如 ollama
• Model：填 ollama list 里显示的模型名

前提是模型已经通过 ollama pull 或 ollama create 拉到本地。

6.2 Cherry Studio 的接入步骤

Cherry Studio 这类桌面聊天工具，核心价值是给 Ollama 提供一个好用的对话界面。配置路径一般是：设置 → 模型提供商 → 添加自定义提供商，然后按上面的万能公式填地址。填完之后拉取模型列表，能拉到说明连接成功。

6.3 Claude Code 和 Codex 的接入思路

“Claude Code + CC Switch + Ollama”是最近讨论度很高的组合，但要注意：Claude Code 默认走的是 Anthropic 协议，不能直接把 Ollama 地址填进去。社区里的常见做法是加一个协议转换层（比如 claude-code-router 这类路由工具），由它把 Anthropic 请求转成 OpenAI 兼容请求转发给 Ollama。

Codex CLI 则更直接一点，只要设置好 OpenAI 兼容地址就能指定本地模型。官方客户端通过环境变量指定 Base URL，模型名填 qwen2.5-local ，就能在终端里和本地模型对话。

不管接哪个工具，我都建议先回到 5.2 节，用 curl 确认 API 通不通。链路越长，越要一层一层验证：先 CLI 直接对话，再 curl 调 API，最后才接客户端。很多“接不上”的问题，其实早在 API 层就断了。

6.4 不想折腾 UI，直接上容器版 WebUI

如果不想装桌面客户端，还可以一行命令跑起 Open WebUI：

docker run -d -p 3000:8080 --add-host=host.docker.internal:host-gateway -v open-webui:/app/backend/data --name open-webui ghcr.io/open-webui/open-webui:main

浏览器打开 http://127.0.0.1:3000 ，在后台配置 Ollama 地址时填 http://host.docker.internal:11434 。这套组合更适合想给团队提供内网 AI 服务的场景。

---

最后分享一点个人体会。我在不同机器上装过很多次 Ollama，踩过 C 盘爆红、模型反复拉取失败、WSL 403 这些坑之后，现在的固定套路是：先规划好磁盘位置，再动手安装；装完第一件事不是急着下大模型，而是先 pull 一个小模型跑通链路；下载慢就不纠结，直接走离线导入。这套流程走顺之后，Ollama 的安装部署基本就是二十分钟内的事。

本文还有配套的精品资源，点击获取