修改环境变量ollama_models

模型与算力

讲清 OLLAMA_MODELS 环境变量怎么改、改完为什么不生效,以及排查顺序与验证动作。

模型越下越多,系统盘先扛不住,于是你想把模型挪到大盘,按教程设了 OLLAMA_MODELS,重启 ollama 却发现新目录还是空的、旧模型还在原位。这篇不解释环境变量本身是什么意思,只给配置位置、生效条件和一套排查顺序,让你五分钟内判断是变量没读到、还是 ollama 用了别的路径。

模型越下越多,系统盘先扛不住,于是你想把模型挪到大盘,按教程设了 OLLAMA_MODELS,重启 ollama 却发现新目录还是空的、旧模型还在原位。别急着怀疑变量名拼错了,绝大多数情况是变量写在了 ollama 根本不会读的那一层。

这篇不解释环境变量本身是什么意思,只给配置位置、生效条件和一套排查顺序,让你几分钟内判断是变量没读到、还是 ollama 用了别的路径。先想清楚一件事:ollama 是被谁拉起来的。

先分清在哪写这个变量

同一个变量名,写在不同层级,效果完全不同。终端里 export 出来的那份,只对当前 shell 和它启动的子进程有效;如果 ollama 是被系统服务、图形界面或容器拉起来的,它根本不看你的 shell。

systemd 服务启动
读的是服务单元里的 Environment 配置,不是终端 export 的那份
macOS 图形界面启动
不继承 shell 的 profile,写进 ~/.zshrc 往往白写
Windows
要区分用户变量与系统变量,服务模式和手动命令行模式读的位置不一样
容器启动
变量要写在容器环境里,宿主机的 export 与它无关

结论很简单:先确认 ollama 是被谁拉起来的,再去对应位置写,别在错误的层改。判断方法是在终端里看进程的父进程和服务来源,或者在系统服务管理器里找 ollama 这一项。

改完怎么确认它真的生效

很多人改完变量后,只在自己 shell 里 echo 一下看到值了,就以为成了。这个验证动作是无效的——你验证的是 shell,不是 ollama 进程。要验证就验证进程实际读到的环境。

  1. 查进程实际环境新开一个终端,直接查 ollama 进程或服务单元的环境变量,而不是查你自己 shell 的那份。两个结果不一致,说明写错了层级。
  2. 拉小模型看落点用一个新模型做验证:pull 一个小模型,看它落在哪个目录。比翻文档快,也比猜准。
  3. 迁移旧模型用移目录或复制的方式把旧模型搬过去,别让新目录是空的还以为成功。新目录空着,多半说明变量压根没生效。
  4. 一起重启同时开着的客户端、容器、图形界面如果在变量生效前启动过,要一起重启,它们缓存的是旧路径。

设了却不生效,按这个顺序查

设了变量但模型还落在旧路径,不用东试西试。按下面的顺序查,基本两三步就能定位。顺序不能乱,从粗到细,能省掉大量重复动作。

排查顺序查什么典型表现
一启动方式服务、容器、图形界面还是前台命令,读变量的位置都不同
二写法路径里有空格、末尾斜杠、引号残留,变量被当成非法值
三权限目标目录属主不是运行 ollama 的用户,静默落回默认路径
四覆盖docker 挂载、compose 文件或上层脚本重新定义了同名变量,以最后写入的为准

这四步里,一和三最容易被跳过。启动方式决定你有没有写对地方,权限决定它愿不愿意用你给的地方——权限不对时 ollama 通常不报错,只是安静地退回默认路径,这也是最难查的一种。

  • 启动方式是服务:去服务单元里查 Environment,别在 profile 里折腾
  • 启动方式是容器:去容器或编排文件里查,宿主机改了不起作用
  • 路径带空格或末尾斜杠:换成干净路径再试,别带引号
  • 权限不对:确认目标目录属主是运行 ollama 的那个用户
  • 被上层覆盖:查最后写入同名变量的地方,以它为准

多环境并存时最容易踩的坑

一台机器上装了桌面版又装了命令行版,或者既在宿主机跑又在容器里跑,就会出现「一半模型在这儿一半在那儿」。这类问题不是变量本身错了,而是两个实例各认一套配置。

判断标准是看进程列表里同时有几个 ollama 实例。大于一个,就先决定哪套是你的主用环境,另一个要么停掉,要么把路径也指过去。换目录后旧路径还留着缓存和清单文件,清不清看你还需不需要回退;要回退就同步改回变量。

团队共享一台机器时,把路径写进个人 shell 配置,只对你自己生效,别人照样踩坑。这种情况应该写进共享的服务或编排层,别写个人 profile。

动手前过一遍的清单

改之前把下面几件事确认一遍,能避免大部分返工。这份清单的核心思路是:先确认物理条件,再确认写入位置,最后留回退路。

  • 确认磁盘:新路径挂的是大盘,且剩余空间够下一个量级的模型
  • 确认启动方式,决定变量写到服务单元、profile、编排文件还是系统设置
  • 写完后按「新开终端查环境 → 拉小模型验证落点 → 迁移旧模型」三步走
  • 留一条回退路:记下原路径,改回时不用重新下模型
  • 多实例环境先决定主用哪套,别让两个实例各写各的

如果排查完还是不放心,可以到站内的模型资料库和中转站检测页面核对当时的路径说明与可信度信息,看是不是你用的那个分发版本改了行为。

下一步改完环境变量后,建议顺手看一下中转站与模型分发的可信度说明,判断你用的那套分发有没有额外的路径约定,避免下次换版本又要重查一遍。

常见问题

为什么我在终端 export 了变量,models 目录还是老的?

大概率 ollama 是后台服务或图形界面拉起来的,它不读你当前终端的变量。改服务单元、系统环境变量或应用自身设置里对应那份,再重启进程;export 只对同一 shell 里前台启动的命令有效。

旧模型要不要重新下载?

不用,模型是文件,把原目录内容移到新目录即可。注意两点:移动前停掉 ollama,避免清单写到一半;移动后确认新目录的属主与权限跟运行用户一致,否则会出现路径生效但列表为空。

变量路径写对了,仍然报找不到模型,还查什么?

先看是不是容器或上层脚本重新定义了同名变量,最后写入的会覆盖你那份;再看路径里有没有空格、中文或末尾斜杠。逐条排除后还不行,就到站内质量检测工具里对一遍本机服务状态,再回到进程环境确认。

本文依据各平台公开文档与官方公告整理,只做中文归纳;具体做法、参数与限制以官方文档为准。