1. 为什么我要专门写一篇 OR-Tools 的安装笔记先说结论OR-Tools 的安装是目前我接触过的运筹优化类库里面最简单的一个没有之一。打开终端敲一行pip install ortools等个几十秒导入不报错你就已经具备了搭建排产模型、排班模型、路径规划模型、装箱切割模型的全部能力。听起来像广告词但这就是客观事实。相比之下有些求解器你要先申请许可、再填环境变量、再配共享库路径光是能跑起来就能耗掉一个下午。那为什么还要写这篇文章因为我带过的实习生、合作过的同事、以及社群里问过我问题的人几乎都在看起来最简单的这一步上翻过车。有人装完了导入报 DLL 加载失败有人本机跑得好好的打包到服务器就崩有人装完发现和项目里已有的 TensorFlow 打架有人用 Anaconda 装完发现 PyCharm 识别不到内核。这些问题不是 OR-Tools 特有的坑是 Python 生态里所有 C 扩展库共通的坑只是恰好在你装 OR-Tools 的时候撞上了。所以这篇东西的定位很明确它是一份从零开始、覆盖 Windows / macOS / Linux 三个平台、包含离线场景和工程化收尾的 OR-Tools 安装实操记录。如果你是完全没碰过优化求解器的新手跟着走一遍就能跑通第一个模型如果你已经有 Python 环境想快速确认自己机器上该用哪种装法可以直接跳到第 2 章和第 4 章如果你已经在用 OR-Tools 但偶尔被依赖冲突折磨第 6 章的排查速查表应该对你更有用。我尽量不写成官方文档的复读。官方文档告诉你怎么装我这里会多讲一层为什么这么装、这样装会有什么副作用、踩过之后才发现的问题在哪。所有涉及版本号、路径、命令的地方我都会说明怎么自己验证而不是让你照抄一个可能过期的答案。2. 先把话说清楚OR-Tools 装完之后你手里多了什么2.1 它不是单一算法而是一整套求解器工具箱很多人对 OR-Tools 的第一印象是一个求解器这个理解不太准确。准确的说法是它是一组求解器的统一封装外加一层建模 API。你通过 Python 写模型底层可能调用完全不同的求解引擎。这件事直接决定了你的安装体验因为不同引擎的依赖和平台支持情况是不一样的。按我平时的使用频率排一下主要用到这几块CP-SAT 求解器处理约束满足和组合优化问题的绝对主力整数变量、布尔变量、区间变量、全局约束都支持排班、排产、调度、装箱这些场景基本靠它。这是 OR-Tools 这几年最值得用的部分性能提升幅度很大。线性规划求解族GLOP 是自带的单纯形实现PDLP 是后来的大规模一阶算法实现CLP/CBC 来自 COIN-OR 项目。连续变量、线性约束的模型走这条路。路由求解库专门针对车辆路径、旅行商这类问题做了大量启发式策略比自己拿 CP-SAT 硬建模省事得多。图算法库最短路径、最大流、最小费用流这些接口简单拿来就用。外部求解器接口如果你手上有 Gurobi、CPLEX 这类商业求解器的许可OR-Tools 也能把它们当一个后端来调。关键点在于上面这些大部分能力在你执行那一行 pip 安装命令之后就已经全部就位了不需要你再单独去编译哪个子模块。这是它跟我给你个源码你自己编那类库的最大区别。2.2 为什么偏偏是安装这一步最容易被写烂我观察到一个现象越简单的安装步骤网上流传的错误信息越多。原因不难理解简单的东西大家觉得没什么可写的于是随手复制一段旧命令发出去几年过去版本一变那段命令就成了坑。OR-Tools 相关的搜索结果里我见过不少还在推荐十几年前做法的内容比如手动下载压缩包、手动拷贝动态库到系统目录、手动设置LD_LIBRARY_PATH。这些做法在当年是必要的现在的 wheel 包里已经把动态库打包好了照做反而容易搞出问题。另一个原因是 Python 环境的复杂性。同一台机器上系统自带的 Python、官网下载的 Python、Anaconda 的 base 环境、conda 建的各种虚拟环境、IDE 自带的解释器全都可能被pip指向。你敲的是一条命令实际装到了哪个环境里很多时候你自己都不知道。等运行的时候发现明明装了却导入不了其实装到了另一个地方。注意判断装没装对地方最可靠的办法不是看pip list而是在你实际运行代码的那个解释器里执行import sys; print(sys.executable)再把它的路径和pip -V输出的路径对比。两个路径不一致问题就找到了。2.3 什么样的读者适合按这篇文章走我把适用人群分三类你可以对号入座第一类是完全的新手可能连 Python 都没装利索只是想跑个排班或者路径规划的小例子。这类读者建议按顺序读重点看第 3 章和第 5 章先把环境理顺再动手。第二类是有 Python 基础的开发者手上有现成项目想在这个项目里加一个优化模块。这类读者重点关注第 3.3 节的依赖冲突检查和第 7 章的版本锁定因为你最大的风险不是装不上而是把现有环境搞坏。第三类是要在服务器或内网环境部署的人。这类读者直接看第 6.3 节的离线安装和 6.4 节的速查表你面临的场景和单机开发完全不同。3. 安装路线怎么选四条路横向对比3.1 路线一pip 直装90% 的人用这一条就够了这是最省事的做法也是标题里最简单三个字的来源。pip install ortools就这一行。它会从 Python 包索引拉取与你当前 Python 版本、操作系统、CPU 架构匹配的预编译 wheel 包解压安装完毕。整个过程不需要编译器不需要 C 工具链不需要额外的系统依赖。我第一次在 Windows 上装的时候心理预期是又要折腾一下午结果一分多钟就结束了当时确实有点意外。为什么能做到这么简单因为 OR-Tools 的发布流程里已经替你做了大量工作每个平台、每个 Python 小版本都单独构建了 wheel把 C 编译产物和运行时库全部打进去。你拿到的是一个开箱即用的二进制包而不是需要现场编译的源码。如果你所在网络对默认源访问不畅可以临时指定一个就近的镜像源比如pip install ortools -i https://pypi.tuna.tsinghua.edu.cn/simple这个做法的意义只有一个缩短下载时间。它不改变你装到的包内容包本身是同一个。装完想确认一下版本直接用下面这条pip show ortools输出里的 Version 字段就是当前版本。我建议你把这个版本号记下来后面排查问题、写依赖清单都用得上。3.2 路线二conda 路线环境隔离党的选择如果你平时用 conda 或 mamba 管理环境那更推荐走这条conda create -n opt python3.11 -y conda activate opt conda install -c conda-forge ortools -y用 conda 装的好处不在于能装上而在于依赖一致性由 conda 的解析器统一负责。OR-Tools 依赖 numpy、protobuf、absl-py 这几个包如果你的环境里还有别的库也依赖它们conda 会在安装时把整套依赖关系算一遍尽量给出一组互相兼容的版本组合。pip 在这件事上就弱一些它只看当前要装的包不太管别人的死活。代价是 conda 的求解过程慢尤其是环境里包比较多的时候可能要转好几分钟。这时候换 mamba 会明显快一些它用的是同一套渠道只是解析算法效率高得多。还有一个细节值得提醒conda-forge 渠道上的包名和 PyPI 上不一定完全一致。如果你搜不到先用conda search -c conda-forge ortools确认一下实际包名别凭印象敲。我自己就吃过这个亏凭记忆敲了个名字结果报 PackagesNotFoundError折腾半天才发现是名字写错了。3.3 路线三源码编译除非有特殊需求否则别碰源码编译这条路我走过一次纯粹是为了验证能不能编出来实际项目里从没这么干过。它适合两种极端情况一是你的目标平台没有现成 wheel比如某些特殊的 ARM 架构设备二是你需要修改 OR-Tools 的内部实现。编译需要的东西不少CMake、C 编译器、各种第三方依赖abseil、protobuf 等整个构建过程对内存和磁盘都有一定要求。而且编译出来的东西需要你自己管理动态库路径后续升级也更麻烦。我的态度很明确除非你已经确认没有 wheel 可用否则不要走这条路。判断方法很简单先跑一次 pip 安装如果它报 Could not find a version that satisfies the requirement 或者拉下来了源码包开始编译那才说明你的平台确实没有预编译包。3.4 路线四容器或子系统不想污染本机环境就用它还有一种情况越来越常见你只是临时想跑个验证脚本不想在本机留下任何痕迹。这时候有两个选择。容器方案docker run --rm -it python:3.11-slim bash pip install ortools python -c from ortools.sat.python import cp_model; print(ok)Windows 上的子系统方案则更适合需要长期使用的场景文件读写和本机互通的体验比容器好很多适合把开发环境整个搬进去。怎么选看你的目的。临时验证用容器用完即删干净利落长期开发用子系统或虚拟机工具链完整编辑器集成也方便。3.5 四条路线的对比表路线命令复杂度装完可控性适用场景主要风险pip 直装极低中绝大多数个人开发场景与现有包冲突conda 安装低高多环境并存、科学计算项目解析慢、渠道差异源码编译高最高特殊平台、需要改源码构建失败、依赖缺失容器 / 子系统中高临时验证、环境隔离环境体积大、图形界面弱这张表是我自己踩完之后的总结不是从文档里抄的。核心判断逻辑就一句话能用预编译包就用预编译包需要环境隔离就在 conda 和容器之间选一个。4. 动手之前把 Python 环境的地基打好4.1 版本匹配这件事比你想的更重要OR-Tools 的每个发布版本都会明确声明支持的 Python 版本范围。这个范围不是随便写的因为 wheel 是按其对应的 Python ABI 编译的如果你的解释器版本不在支持列表里pip 要么找不到匹配的包要么退而求其次去编译源码然后失败。我不想在这里给一个固定的版本对应表因为我写下的数字过几个月就可能失效照抄反而害人。更靠谱的做法是让 pip 自己告诉你pip index versions ortools这条命令会列出当前源上所有可用的 OR-Tools 版本你从中挑一个和你 Python 版本匹配的。另一种方式是直接看候选包pip download ortools --no-deps -d /tmp/probe -v详细日志里会打印出它筛选 wheel 文件名的过程文件名中带有cp311、macosx_11_0_arm64这类标识一眼就能看出它选的是哪个平台的包。这个技巧我强烈建议你掌握因为所有装上了但导入失败的问题追根溯源几乎都和装错了平台的包有关。提示如果你不确定该选哪个 Python 版本选一个当前仍处于维护期的稳定版本比盲目追新要稳妥得多。追新最容易遇到的情况是包还没发布对应的 wheel。4.2 虚拟环境不是可选项是必选项我见过太多人直接在系统 Python 或者 conda 的 base 环境里装东西用了半年之后环境彻底乱掉谁也说不清哪个包的哪个版本是谁装的。虚拟环境的成本几乎为零收益却很大。用 Python 自带的方式创建python -m venv .venvWindows 下激活.venv\Scripts\activateLinux 和 macOS 下激活source .venv/bin/activate激活之后终端的提示符前面一般会出现环境名这时候再执行 pip 安装包就落到这个环境里了和系统环境完全隔离。项目结束不想要了直接把.venv目录删掉就行不留任何残留。关于目录位置我的习惯是放在项目根目录下并且把.venv/写进版本控制忽略文件。这样每个项目一套依赖互不干扰。有人喜欢把所有虚拟环境集中放在一个目录里统一管理这也行只是要注意路径不要太深否则某些工具处理长路径会出问题。4.3 装之前先做一次依赖体检这一步很多人跳过然后就撞上了冲突。检查方式很简单在目标环境里执行pip list重点看三个包numpy、protobuf、absl-py。OR-Tools 对它们有版本要求如果你的环境里这三个包是几十个其他库共用的那么装 OR-Tools 时 pip 可能会尝试升级或降级它们从而影响其他库。我遇到过的真实场景是一个环境里同时有深度学习框架和 OR-Tools前者对 protobuf 有比较严格的上限要求后者希望用较新的版本两者互相拉扯。最后的解决办法是拆成两个环境用的时候切换比在一个环境里强行凑合要清爽得多。还有一种情况是自己写的代码间接依赖了某个特定版本升级后行为变了。所以装之前的体检不是形式主义它决定了你后面会不会花两个小时去排查一个本来可以避免的问题。5. 手把手实操三个平台的完整流程5.1 Windows 下的完整流程我把 Windows 上的步骤拆成五步按顺序执行即可。第一步确认 Python 可用。打开 PowerShell 或命令提示符执行python --version pip --version两条命令都要能正常输出。如果python命令没反应说明 Python 没装或者没加进 PATH这时候先去解决这个问题其他的都别急。第二步建虚拟环境并激活命令在 4.2 节已经给过不重复。第三步安装python -m pip install --upgrade pip python -m pip install ortools先升级 pip 这一步看起来多余其实很有必要。旧版 pip 在处理某些 wheel 标签时可能选错包升级一下能避免不少奇怪问题。用python -m pip而不是直接写pip是为了确保调用的是当前解释器对应的那个 pip这是我在多环境机器上养成的习惯。第四步验证导入python -c from ortools.sat.python import cp_model; print(cp_model.__name__)能正常打印说明安装成功。第五步处理可能出现的动态库报错。如果你的系统缺少某些运行时组件导入时会看到类似 DLL load failed 的提示。这种情况下装一下微软官方的 C 运行库通常就能解决。注意要从正规渠道获取别去下载来路不明的安装包。我在 Windows 上遇到过的另一个问题是杀毒软件的实时扫描。它有时候会锁定刚解压出来的动态库文件导致安装过程报权限错误。遇到这种情况把环境目录加进白名单或者临时关掉实时扫描再装一次基本就能过。5.2 macOS 下的完整流程macOS 上的步骤和 Windows 差别不大环境激活命令换成source .venv/bin/activate即可。需要额外注意的是芯片架构。用 Apple Silicon 的机器理论上直接 pip 安装就会拉到 arm64 的 wheel。但如果你是在某种混合环境下运行比如终端本身跑在转译层下pip 可能会误判架构装成 x86_64 的包。后果是能装上、导入也不一定报错但运行性能会明显打折扣因为整个库都在转译层里跑。判断方法python -c import platform; print(platform.machine())输出arm64说明是原生环境输出x86_64说明当前解释器在转译模式下运行。这个信息和你装的 wheel 类型应当匹配。如果不匹配检查一下你的 Python 是怎么装的建议用原生支持 arm64 的发行版本重新装一个解释器。还有一种更省事的做法是在 macOS 上走 conda-forge 渠道它对这个平台的架构区分处理得比较清楚不容易装错。5.3 Linux 和 Ubuntu 下的完整流程Linux 上的安装体验通常最顺因为很多发行版的官方仓库里就有 Python 和 pip依赖也齐全。sudo apt update sudo apt install -y python3 python3-pip python3-venv python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install ortools有一个坑值得单独说部分发行版的系统 Python 受外部管理保护直接 pip 安装会报 externally-managed-environment 错误。这不是 OR-Tools 的问题是发行版为了防止你搞坏系统 Python 而设的保护。正确的应对方式是建虚拟环境也就是上面流程里的做法。如果你确实需要在系统级安装可以用系统包管理器装如果仓库里有对应的包或者使用--break-system-packages参数强行安装。但我很不推荐后者理由和 4.2 节说的一样系统 Python 是很多系统工具的依赖动它风险太高。另外如果你用的是精简容器镜像可能连venv模块都没装需要额外装一次python3-venv。这个报错信息不太直观第一次遇到容易懵。5.4 三种系统的差异速览环节WindowsmacOSLinux环境激活.venv\Scripts\activatesource .venv/bin/activatesource .venv/bin/activate常见额外依赖C 运行库无注意架构venv 模块主要风险杀软锁定、PATH 混乱架构误判系统 Python 保护推荐安装方式pippip 或 condapip这张表里的主要风险一栏是我三个平台都实际用过之后填的不是猜的。你会发现真正的问题都不在安装命令本身而在系统层面的环境差异上。6. 装完不算完验证与第一个能跑的模型6.1 三步验证法我不建议装完就直接上复杂代码先做三级验证出了问题好定位。第一级确认能导入顶层模块python -c import ortools; print(ortools.__file__)这条能过说明包找到了路径也对。第二级确认核心子模块可用python -c from ortools.sat.python import cp_model; print(sat ok) python -c from ortools.linear_solver import pywraplp; print(lp ok) python -c from ortools.constraint_solver import routing_enums_pb2; print(routing ok)这三条分别对应约束求解、线性规划、路由求解三大块。如果第一条过了第二条挂了说明动态库加载有问题和第 5.1 节说的运行库缺失是同一类问题。第三级跑一个真正能求出答案的小模型见下一节。分三级的意义在于一旦出问题你能立刻知道是包没装对还是依赖有问题还是代码写错了。一上来就跑复杂脚本报错了你会无从下手。6.2 一个能打印出可行解的完整例子下面这段代码是我平时用来做冒烟测试的逻辑简单但用到了建模、约束、目标函数、求解、结果读取的完整链路from ortools.sat.python import cp_model def main(): model cp_model.CpModel() x model.NewIntVar(0, 10, x) y model.NewIntVar(0, 10, y) model.Add(x y 12) model.Add(x - y 2) model.Maximize(3 * x 2 * y) solver cp_model.CpSolver() solver.parameters.max_time_in_seconds 5.0 status solver.Solve(model) print(status:, solver.StatusName(status)) if status in (cp_model.OPTIMAL, cp_model.FEASIBLE): print(x , solver.Value(x)) print(y , solver.Value(y)) print(objective , solver.ObjectiveValue()) print(wall time , solver.WallTime()) if __name__ __main__: main()正常输出会告诉你状态是 OPTIMAL以及 x、y 的取值和目标值。看到这些数字就说明你的 OR-Tools 已经完全可用了。这段代码里有两个细节值得说。一是max_time_in_seconds参数它给了求解过程一个时间上限防止某个模型意外跑很久把终端卡住我在写测试脚本时习惯性加上。二是状态判断Solve的返回值除了最优和可行还可能是不可行或者未知实际项目里一定要处理这些分支不能假定一定有解。6.3 求解器后端和日志开关线性规划部分支持切换后端写法是在创建求解器时传名字from ortools.linear_solver import pywraplp solver pywraplp.Solver.CreateSolver(GLOP)常见的名字有 GLOP、PDLP、CBC 这几个。如果传了不支持的名称返回的对象会是空值所以创建之后要判空if solver is None: raise RuntimeError(solver not available)这个判空很多人都忘了写然后在后面调用方法时得到一个莫名其妙的属性错误其实真正的原因在第一行。调试阶段打开日志会很有帮助solver.EnableOutput()打开之后求解器会打印搜索过程的统计信息包括找到的界、节点数、耗时等等。这些信息在看模型为什么慢、为什么切不出来的时候特别有用。上线时记得关掉否则日志量会比较可观。7. 踩坑实录常见报错和排查思路7.1 导入阶段的几类典型报错报错一找不到模块。提示是 ModuleNotFoundError: No module named ortools。这个最常见原因八成是装到了另一个环境。按第 2.2 节的提示对比解释器路径和 pip 路径十秒钟就能定位。报错二动态库加载失败。提示里带 DLL load failed 或者 cannot open shared object file。这是运行库缺失或版本不匹配。Windows 上装一下 C 运行库Linux 上检查一下基础库依赖通常能解决。如果还是不行用pip download把 wheel 拉下来解压看看里面有哪些动态库文件再对照系统缺哪个。报错三导入时抛出 numpy 相关异常。这种情况说明 numpy 版本和 OR-Tools 期望的不一致。解决办法是先卸掉 numpy再重装一个匹配的版本或者干脆重建环境按顺序安装。注意遇到导入报错时先把完整报错信息从头到尾读一遍。Python 的报错链是从下往上看的最底下那一行才是真正的起因中间那些 During handling of the above exception 是中间过程。我见过不少人只看最后一行就开始搜结果搜到的答案完全不对口。7.2 依赖冲突的处理顺序依赖冲突的处理有个原则先隔离再降级最后才是改代码。隔离的意思是把 OR-Tools 放到独立环境里这是成本最低的方案大多数情况下直接解决问题。如果必须共存那就尝试锁定版本。做法是在安装时明确指定各个包的版本让 pip 不去做自主升级决策pip install numpy2 protobuf4.21,5 ortools具体版本区间要根据你的实际报错来定我这里给的是示意写法不是通用答案。判断依据是报错信息里提到的版本号以及pip list里的现状。改代码是最后的手段因为一旦你为了迁就依赖去改业务逻辑技术债就埋下了。7.3 内网和离线环境怎么装内网部署是个很现实的场景我做过好几次流程整理如下。在有网络的机器上把 wheel 和它的全部依赖一起下载下来pip download ortools -d ./offline_pkgs注意这里不要加--no-deps因为你需要把依赖一起打包带过去。下载完成后把整个目录拷到内网机器上然后pip install --no-index --find-links./offline_pkgs ortools--no-index表示完全不访问网络索引--find-links表示从本地目录找包。这两个参数配合使用就是标准的离线安装姿势。有几个细节容易忽略。第一下载时的机器必须和目标机器有相同的操作系统、CPU 架构和 Python 版本否则拉下来的 wheel 用不了。第二如果目标机器上已经有一些依赖可能会和离线包里的版本冲突稳妥的做法是提前一天先在同样配置的机器上演练一遍。第三下载目录里的文件别改名pip 是靠文件名解析包信息的。7.4 排查速查表现象可能原因优先排查动作提示找不到模块装到了别的环境对比解释器路径与 pip 路径动态库加载失败缺运行时库或架构不符检查平台标识与运行库导入时 numpy 报错numpy 版本不兼容单独重装匹配版本的 numpy安装过程卡住网络访问不畅指定就近镜像源重试安装报权限错误杀软锁定或目录无写权限加白名单或换虚拟环境求解器对象为空后端名称拼写错误打印后端名并核对求解耗时异常长模型规模或参数设置问题打开日志看搜索过程这张表我建议你收藏一下。实际排查的时候九成的情况都落在前四行里按顺序试一遍基本都能解决。8. 工程化收尾把环境固定下来8.1 锁定版本别让环境自己漂移开发环境最怕的一件事是今天跑得好好的明天同事拉下来就报错。原因往往是某个包悄悄升了版本。解决办法是把依赖写进清单文件并且锁定版本。pip freeze requirements.txt这个文件会把当前环境所有包及版本记录下来。别人拿到之后pip install -r requirements.txt就能复现出一套几乎一模一样的环境。如果你的项目依赖比较复杂可以考虑用带哈希校验的锁定工具它会把依赖树完整展开并校验包的完整性更适合对可复现性要求高的场景。我个人在个人项目里的做法比较轻量只锁顶层直接依赖用兼容性约束而不是精确等于。比如写成ortools9.0,10这样小版本升级不会打破环境大版本升级时会提前知道要测试。团队协作的项目则倾向于精确锁定减少沟通成本。8.2 持续集成里的安装写法如果项目跑了自动化测试测试环境里的安装要注意两点一是使用无缓存安装确保每次都拉最新的匹配版本二是加超时和重试参数避免网络抖动导致构建失败。pip install --no-cache-dir --timeout 60 --retries 3 -r requirements.txt这几个参数都是我在实际构建里踩过坑之后加上去的。没有重试的那段时间构建失败率明显偏高而且失败原因还不好判断日志里就一句连接中断。另外自动化环境里建议固定 Python 镜像的版本别用浮动标签。用浮动标签的后果是某天上游更新了基础镜像你的构建突然就红了排查起来很浪费时间。8.3 多个版本共存的场景有些时候你确实需要同时保留两个不同大版本的 OR-Tools比如老项目在维护期不能升级新项目要用新特性。这件事用虚拟环境很好解决一个环境装一个版本需要哪个激活哪个。不建议在同一环境里用pip install ortoolsx.y反复覆盖虽然技术上可行但依赖树会越来越乱容易出现某些依赖留在旧版本上、某些已经升级的混合状态。这种状态下报的错往往很难解释。如果你用编辑器写代码记得检查它当前配置的解释器是不是你想的那个。我遇到过好几次明明激活了环境终端里能跑编辑器里却报错的情况最后发现是编辑器的解释器设置没跟着变。8.4 一条命令的极简路径回顾写到这里如果你只是想要最短路径把下面这段走完就够了python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate python -m pip install --upgrade pip python -m pip install ortools python -c from ortools.sat.python import cp_model; print(ok)四条命令加一条验证。我特意把这个顺序写成这样而不是直接一句pip install ortools是因为中间那两步建环境、升 pip花掉的时间不超过二十秒但能挡掉后面绝大部分麻烦。省这二十秒可能要花两小时去救环境这笔账怎么算都不划算。最后分享一个我个人的习惯。每次在新机器或新环境里装完 OR-Tools我都会把第 6.2 节那段小模型跑一遍把输出结果贴进项目的环境说明文档里顺便记下当时的版本号和时间。看起来很啰嗦但这个记录至少帮我省过三次时间一次是服务器环境迁移后行为变了靠对比版本号找到了原因一次是同事复现不了我的结果一看版本差了一个大版本还有一次是升级之后某个参数默认值改了翻记录才发现。另外OR-Tools 的版本迭代比较活跃遇到问题的时候除了搜报错信息也值得去翻一翻对应版本的发布说明很多行为变化都会在那里写清楚。比起在论坛里翻半天不知道有没有用的帖子这条路通常更直接。 
长河君 · 2026/10/1 1:21:58 · 阅读 1.2k OR-Tools 安装笔记：全平台避坑、虚拟环境与离线部署
1. 为什么我要专门写一篇 OR-Tools 的安装笔记先说结论OR-Tools 的安装是目前我接触过的运筹优化类库里面最简单的一个没有之一。打开终端敲一行pip install ortools等个几十秒导入不报错你就已经具备了搭建排产模型、排班模型、路径规划模型、装箱切割模型的全部能力。听起来像广告词但这就是客观事实。相比之下有些求解器你要先申请许可、再填环境变量、再配共享库路径光是能跑起来就能耗掉一个下午。那为什么还要写这篇文章因为我带过的实习生、合作过的同事、以及社群里问过我问题的人几乎都在看起来最简单的这一步上翻过车。有人装完了导入报 DLL 加载失败有人本机跑得好好的打包到服务器就崩有人装完发现和项目里已有的 TensorFlow 打架有人用 Anaconda 装完发现 PyCharm 识别不到内核。这些问题不是 OR-Tools 特有的坑是 Python 生态里所有 C 扩展库共通的坑只是恰好在你装 OR-Tools 的时候撞上了。所以这篇东西的定位很明确它是一份从零开始、覆盖 Windows / macOS / Linux 三个平台、包含离线场景和工程化收尾的 OR-Tools 安装实操记录。如果你是完全没碰过优化求解器的新手跟着走一遍就能跑通第一个模型如果你已经有 Python 环境想快速确认自己机器上该用哪种装法可以直接跳到第 2 章和第 4 章如果你已经在用 OR-Tools 但偶尔被依赖冲突折磨第 6 章的排查速查表应该对你更有用。我尽量不写成官方文档的复读。官方文档告诉你怎么装我这里会多讲一层为什么这么装、这样装会有什么副作用、踩过之后才发现的问题在哪。所有涉及版本号、路径、命令的地方我都会说明怎么自己验证而不是让你照抄一个可能过期的答案。2. 先把话说清楚OR-Tools 装完之后你手里多了什么2.1 它不是单一算法而是一整套求解器工具箱很多人对 OR-Tools 的第一印象是一个求解器这个理解不太准确。准确的说法是它是一组求解器的统一封装外加一层建模 API。你通过 Python 写模型底层可能调用完全不同的求解引擎。这件事直接决定了你的安装体验因为不同引擎的依赖和平台支持情况是不一样的。按我平时的使用频率排一下主要用到这几块CP-SAT 求解器处理约束满足和组合优化问题的绝对主力整数变量、布尔变量、区间变量、全局约束都支持排班、排产、调度、装箱这些场景基本靠它。这是 OR-Tools 这几年最值得用的部分性能提升幅度很大。线性规划求解族GLOP 是自带的单纯形实现PDLP 是后来的大规模一阶算法实现CLP/CBC 来自 COIN-OR 项目。连续变量、线性约束的模型走这条路。路由求解库专门针对车辆路径、旅行商这类问题做了大量启发式策略比自己拿 CP-SAT 硬建模省事得多。图算法库最短路径、最大流、最小费用流这些接口简单拿来就用。外部求解器接口如果你手上有 Gurobi、CPLEX 这类商业求解器的许可OR-Tools 也能把它们当一个后端来调。关键点在于上面这些大部分能力在你执行那一行 pip 安装命令之后就已经全部就位了不需要你再单独去编译哪个子模块。这是它跟我给你个源码你自己编那类库的最大区别。2.2 为什么偏偏是安装这一步最容易被写烂我观察到一个现象越简单的安装步骤网上流传的错误信息越多。原因不难理解简单的东西大家觉得没什么可写的于是随手复制一段旧命令发出去几年过去版本一变那段命令就成了坑。OR-Tools 相关的搜索结果里我见过不少还在推荐十几年前做法的内容比如手动下载压缩包、手动拷贝动态库到系统目录、手动设置LD_LIBRARY_PATH。这些做法在当年是必要的现在的 wheel 包里已经把动态库打包好了照做反而容易搞出问题。另一个原因是 Python 环境的复杂性。同一台机器上系统自带的 Python、官网下载的 Python、Anaconda 的 base 环境、conda 建的各种虚拟环境、IDE 自带的解释器全都可能被pip指向。你敲的是一条命令实际装到了哪个环境里很多时候你自己都不知道。等运行的时候发现明明装了却导入不了其实装到了另一个地方。注意判断装没装对地方最可靠的办法不是看pip list而是在你实际运行代码的那个解释器里执行import sys; print(sys.executable)再把它的路径和pip -V输出的路径对比。两个路径不一致问题就找到了。2.3 什么样的读者适合按这篇文章走我把适用人群分三类你可以对号入座第一类是完全的新手可能连 Python 都没装利索只是想跑个排班或者路径规划的小例子。这类读者建议按顺序读重点看第 3 章和第 5 章先把环境理顺再动手。第二类是有 Python 基础的开发者手上有现成项目想在这个项目里加一个优化模块。这类读者重点关注第 3.3 节的依赖冲突检查和第 7 章的版本锁定因为你最大的风险不是装不上而是把现有环境搞坏。第三类是要在服务器或内网环境部署的人。这类读者直接看第 6.3 节的离线安装和 6.4 节的速查表你面临的场景和单机开发完全不同。3. 安装路线怎么选四条路横向对比3.1 路线一pip 直装90% 的人用这一条就够了这是最省事的做法也是标题里最简单三个字的来源。pip install ortools就这一行。它会从 Python 包索引拉取与你当前 Python 版本、操作系统、CPU 架构匹配的预编译 wheel 包解压安装完毕。整个过程不需要编译器不需要 C 工具链不需要额外的系统依赖。我第一次在 Windows 上装的时候心理预期是又要折腾一下午结果一分多钟就结束了当时确实有点意外。为什么能做到这么简单因为 OR-Tools 的发布流程里已经替你做了大量工作每个平台、每个 Python 小版本都单独构建了 wheel把 C 编译产物和运行时库全部打进去。你拿到的是一个开箱即用的二进制包而不是需要现场编译的源码。如果你所在网络对默认源访问不畅可以临时指定一个就近的镜像源比如pip install ortools -i https://pypi.tuna.tsinghua.edu.cn/simple这个做法的意义只有一个缩短下载时间。它不改变你装到的包内容包本身是同一个。装完想确认一下版本直接用下面这条pip show ortools输出里的 Version 字段就是当前版本。我建议你把这个版本号记下来后面排查问题、写依赖清单都用得上。3.2 路线二conda 路线环境隔离党的选择如果你平时用 conda 或 mamba 管理环境那更推荐走这条conda create -n opt python3.11 -y conda activate opt conda install -c conda-forge ortools -y用 conda 装的好处不在于能装上而在于依赖一致性由 conda 的解析器统一负责。OR-Tools 依赖 numpy、protobuf、absl-py 这几个包如果你的环境里还有别的库也依赖它们conda 会在安装时把整套依赖关系算一遍尽量给出一组互相兼容的版本组合。pip 在这件事上就弱一些它只看当前要装的包不太管别人的死活。代价是 conda 的求解过程慢尤其是环境里包比较多的时候可能要转好几分钟。这时候换 mamba 会明显快一些它用的是同一套渠道只是解析算法效率高得多。还有一个细节值得提醒conda-forge 渠道上的包名和 PyPI 上不一定完全一致。如果你搜不到先用conda search -c conda-forge ortools确认一下实际包名别凭印象敲。我自己就吃过这个亏凭记忆敲了个名字结果报 PackagesNotFoundError折腾半天才发现是名字写错了。3.3 路线三源码编译除非有特殊需求否则别碰源码编译这条路我走过一次纯粹是为了验证能不能编出来实际项目里从没这么干过。它适合两种极端情况一是你的目标平台没有现成 wheel比如某些特殊的 ARM 架构设备二是你需要修改 OR-Tools 的内部实现。编译需要的东西不少CMake、C 编译器、各种第三方依赖abseil、protobuf 等整个构建过程对内存和磁盘都有一定要求。而且编译出来的东西需要你自己管理动态库路径后续升级也更麻烦。我的态度很明确除非你已经确认没有 wheel 可用否则不要走这条路。判断方法很简单先跑一次 pip 安装如果它报 Could not find a version that satisfies the requirement 或者拉下来了源码包开始编译那才说明你的平台确实没有预编译包。3.4 路线四容器或子系统不想污染本机环境就用它还有一种情况越来越常见你只是临时想跑个验证脚本不想在本机留下任何痕迹。这时候有两个选择。容器方案docker run --rm -it python:3.11-slim bash pip install ortools python -c from ortools.sat.python import cp_model; print(ok)Windows 上的子系统方案则更适合需要长期使用的场景文件读写和本机互通的体验比容器好很多适合把开发环境整个搬进去。怎么选看你的目的。临时验证用容器用完即删干净利落长期开发用子系统或虚拟机工具链完整编辑器集成也方便。3.5 四条路线的对比表路线命令复杂度装完可控性适用场景主要风险pip 直装极低中绝大多数个人开发场景与现有包冲突conda 安装低高多环境并存、科学计算项目解析慢、渠道差异源码编译高最高特殊平台、需要改源码构建失败、依赖缺失容器 / 子系统中高临时验证、环境隔离环境体积大、图形界面弱这张表是我自己踩完之后的总结不是从文档里抄的。核心判断逻辑就一句话能用预编译包就用预编译包需要环境隔离就在 conda 和容器之间选一个。4. 动手之前把 Python 环境的地基打好4.1 版本匹配这件事比你想的更重要OR-Tools 的每个发布版本都会明确声明支持的 Python 版本范围。这个范围不是随便写的因为 wheel 是按其对应的 Python ABI 编译的如果你的解释器版本不在支持列表里pip 要么找不到匹配的包要么退而求其次去编译源码然后失败。我不想在这里给一个固定的版本对应表因为我写下的数字过几个月就可能失效照抄反而害人。更靠谱的做法是让 pip 自己告诉你pip index versions ortools这条命令会列出当前源上所有可用的 OR-Tools 版本你从中挑一个和你 Python 版本匹配的。另一种方式是直接看候选包pip download ortools --no-deps -d /tmp/probe -v详细日志里会打印出它筛选 wheel 文件名的过程文件名中带有cp311、macosx_11_0_arm64这类标识一眼就能看出它选的是哪个平台的包。这个技巧我强烈建议你掌握因为所有装上了但导入失败的问题追根溯源几乎都和装错了平台的包有关。提示如果你不确定该选哪个 Python 版本选一个当前仍处于维护期的稳定版本比盲目追新要稳妥得多。追新最容易遇到的情况是包还没发布对应的 wheel。4.2 虚拟环境不是可选项是必选项我见过太多人直接在系统 Python 或者 conda 的 base 环境里装东西用了半年之后环境彻底乱掉谁也说不清哪个包的哪个版本是谁装的。虚拟环境的成本几乎为零收益却很大。用 Python 自带的方式创建python -m venv .venvWindows 下激活.venv\Scripts\activateLinux 和 macOS 下激活source .venv/bin/activate激活之后终端的提示符前面一般会出现环境名这时候再执行 pip 安装包就落到这个环境里了和系统环境完全隔离。项目结束不想要了直接把.venv目录删掉就行不留任何残留。关于目录位置我的习惯是放在项目根目录下并且把.venv/写进版本控制忽略文件。这样每个项目一套依赖互不干扰。有人喜欢把所有虚拟环境集中放在一个目录里统一管理这也行只是要注意路径不要太深否则某些工具处理长路径会出问题。4.3 装之前先做一次依赖体检这一步很多人跳过然后就撞上了冲突。检查方式很简单在目标环境里执行pip list重点看三个包numpy、protobuf、absl-py。OR-Tools 对它们有版本要求如果你的环境里这三个包是几十个其他库共用的那么装 OR-Tools 时 pip 可能会尝试升级或降级它们从而影响其他库。我遇到过的真实场景是一个环境里同时有深度学习框架和 OR-Tools前者对 protobuf 有比较严格的上限要求后者希望用较新的版本两者互相拉扯。最后的解决办法是拆成两个环境用的时候切换比在一个环境里强行凑合要清爽得多。还有一种情况是自己写的代码间接依赖了某个特定版本升级后行为变了。所以装之前的体检不是形式主义它决定了你后面会不会花两个小时去排查一个本来可以避免的问题。5. 手把手实操三个平台的完整流程5.1 Windows 下的完整流程我把 Windows 上的步骤拆成五步按顺序执行即可。第一步确认 Python 可用。打开 PowerShell 或命令提示符执行python --version pip --version两条命令都要能正常输出。如果python命令没反应说明 Python 没装或者没加进 PATH这时候先去解决这个问题其他的都别急。第二步建虚拟环境并激活命令在 4.2 节已经给过不重复。第三步安装python -m pip install --upgrade pip python -m pip install ortools先升级 pip 这一步看起来多余其实很有必要。旧版 pip 在处理某些 wheel 标签时可能选错包升级一下能避免不少奇怪问题。用python -m pip而不是直接写pip是为了确保调用的是当前解释器对应的那个 pip这是我在多环境机器上养成的习惯。第四步验证导入python -c from ortools.sat.python import cp_model; print(cp_model.__name__)能正常打印说明安装成功。第五步处理可能出现的动态库报错。如果你的系统缺少某些运行时组件导入时会看到类似 DLL load failed 的提示。这种情况下装一下微软官方的 C 运行库通常就能解决。注意要从正规渠道获取别去下载来路不明的安装包。我在 Windows 上遇到过的另一个问题是杀毒软件的实时扫描。它有时候会锁定刚解压出来的动态库文件导致安装过程报权限错误。遇到这种情况把环境目录加进白名单或者临时关掉实时扫描再装一次基本就能过。5.2 macOS 下的完整流程macOS 上的步骤和 Windows 差别不大环境激活命令换成source .venv/bin/activate即可。需要额外注意的是芯片架构。用 Apple Silicon 的机器理论上直接 pip 安装就会拉到 arm64 的 wheel。但如果你是在某种混合环境下运行比如终端本身跑在转译层下pip 可能会误判架构装成 x86_64 的包。后果是能装上、导入也不一定报错但运行性能会明显打折扣因为整个库都在转译层里跑。判断方法python -c import platform; print(platform.machine())输出arm64说明是原生环境输出x86_64说明当前解释器在转译模式下运行。这个信息和你装的 wheel 类型应当匹配。如果不匹配检查一下你的 Python 是怎么装的建议用原生支持 arm64 的发行版本重新装一个解释器。还有一种更省事的做法是在 macOS 上走 conda-forge 渠道它对这个平台的架构区分处理得比较清楚不容易装错。5.3 Linux 和 Ubuntu 下的完整流程Linux 上的安装体验通常最顺因为很多发行版的官方仓库里就有 Python 和 pip依赖也齐全。sudo apt update sudo apt install -y python3 python3-pip python3-venv python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install ortools有一个坑值得单独说部分发行版的系统 Python 受外部管理保护直接 pip 安装会报 externally-managed-environment 错误。这不是 OR-Tools 的问题是发行版为了防止你搞坏系统 Python 而设的保护。正确的应对方式是建虚拟环境也就是上面流程里的做法。如果你确实需要在系统级安装可以用系统包管理器装如果仓库里有对应的包或者使用--break-system-packages参数强行安装。但我很不推荐后者理由和 4.2 节说的一样系统 Python 是很多系统工具的依赖动它风险太高。另外如果你用的是精简容器镜像可能连venv模块都没装需要额外装一次python3-venv。这个报错信息不太直观第一次遇到容易懵。5.4 三种系统的差异速览环节WindowsmacOSLinux环境激活.venv\Scripts\activatesource .venv/bin/activatesource .venv/bin/activate常见额外依赖C 运行库无注意架构venv 模块主要风险杀软锁定、PATH 混乱架构误判系统 Python 保护推荐安装方式pippip 或 condapip这张表里的主要风险一栏是我三个平台都实际用过之后填的不是猜的。你会发现真正的问题都不在安装命令本身而在系统层面的环境差异上。6. 装完不算完验证与第一个能跑的模型6.1 三步验证法我不建议装完就直接上复杂代码先做三级验证出了问题好定位。第一级确认能导入顶层模块python -c import ortools; print(ortools.__file__)这条能过说明包找到了路径也对。第二级确认核心子模块可用python -c from ortools.sat.python import cp_model; print(sat ok) python -c from ortools.linear_solver import pywraplp; print(lp ok) python -c from ortools.constraint_solver import routing_enums_pb2; print(routing ok)这三条分别对应约束求解、线性规划、路由求解三大块。如果第一条过了第二条挂了说明动态库加载有问题和第 5.1 节说的运行库缺失是同一类问题。第三级跑一个真正能求出答案的小模型见下一节。分三级的意义在于一旦出问题你能立刻知道是包没装对还是依赖有问题还是代码写错了。一上来就跑复杂脚本报错了你会无从下手。6.2 一个能打印出可行解的完整例子下面这段代码是我平时用来做冒烟测试的逻辑简单但用到了建模、约束、目标函数、求解、结果读取的完整链路from ortools.sat.python import cp_model def main(): model cp_model.CpModel() x model.NewIntVar(0, 10, x) y model.NewIntVar(0, 10, y) model.Add(x y 12) model.Add(x - y 2) model.Maximize(3 * x 2 * y) solver cp_model.CpSolver() solver.parameters.max_time_in_seconds 5.0 status solver.Solve(model) print(status:, solver.StatusName(status)) if status in (cp_model.OPTIMAL, cp_model.FEASIBLE): print(x , solver.Value(x)) print(y , solver.Value(y)) print(objective , solver.ObjectiveValue()) print(wall time , solver.WallTime()) if __name__ __main__: main()正常输出会告诉你状态是 OPTIMAL以及 x、y 的取值和目标值。看到这些数字就说明你的 OR-Tools 已经完全可用了。这段代码里有两个细节值得说。一是max_time_in_seconds参数它给了求解过程一个时间上限防止某个模型意外跑很久把终端卡住我在写测试脚本时习惯性加上。二是状态判断Solve的返回值除了最优和可行还可能是不可行或者未知实际项目里一定要处理这些分支不能假定一定有解。6.3 求解器后端和日志开关线性规划部分支持切换后端写法是在创建求解器时传名字from ortools.linear_solver import pywraplp solver pywraplp.Solver.CreateSolver(GLOP)常见的名字有 GLOP、PDLP、CBC 这几个。如果传了不支持的名称返回的对象会是空值所以创建之后要判空if solver is None: raise RuntimeError(solver not available)这个判空很多人都忘了写然后在后面调用方法时得到一个莫名其妙的属性错误其实真正的原因在第一行。调试阶段打开日志会很有帮助solver.EnableOutput()打开之后求解器会打印搜索过程的统计信息包括找到的界、节点数、耗时等等。这些信息在看模型为什么慢、为什么切不出来的时候特别有用。上线时记得关掉否则日志量会比较可观。7. 踩坑实录常见报错和排查思路7.1 导入阶段的几类典型报错报错一找不到模块。提示是 ModuleNotFoundError: No module named ortools。这个最常见原因八成是装到了另一个环境。按第 2.2 节的提示对比解释器路径和 pip 路径十秒钟就能定位。报错二动态库加载失败。提示里带 DLL load failed 或者 cannot open shared object file。这是运行库缺失或版本不匹配。Windows 上装一下 C 运行库Linux 上检查一下基础库依赖通常能解决。如果还是不行用pip download把 wheel 拉下来解压看看里面有哪些动态库文件再对照系统缺哪个。报错三导入时抛出 numpy 相关异常。这种情况说明 numpy 版本和 OR-Tools 期望的不一致。解决办法是先卸掉 numpy再重装一个匹配的版本或者干脆重建环境按顺序安装。注意遇到导入报错时先把完整报错信息从头到尾读一遍。Python 的报错链是从下往上看的最底下那一行才是真正的起因中间那些 During handling of the above exception 是中间过程。我见过不少人只看最后一行就开始搜结果搜到的答案完全不对口。7.2 依赖冲突的处理顺序依赖冲突的处理有个原则先隔离再降级最后才是改代码。隔离的意思是把 OR-Tools 放到独立环境里这是成本最低的方案大多数情况下直接解决问题。如果必须共存那就尝试锁定版本。做法是在安装时明确指定各个包的版本让 pip 不去做自主升级决策pip install numpy2 protobuf4.21,5 ortools具体版本区间要根据你的实际报错来定我这里给的是示意写法不是通用答案。判断依据是报错信息里提到的版本号以及pip list里的现状。改代码是最后的手段因为一旦你为了迁就依赖去改业务逻辑技术债就埋下了。7.3 内网和离线环境怎么装内网部署是个很现实的场景我做过好几次流程整理如下。在有网络的机器上把 wheel 和它的全部依赖一起下载下来pip download ortools -d ./offline_pkgs注意这里不要加--no-deps因为你需要把依赖一起打包带过去。下载完成后把整个目录拷到内网机器上然后pip install --no-index --find-links./offline_pkgs ortools--no-index表示完全不访问网络索引--find-links表示从本地目录找包。这两个参数配合使用就是标准的离线安装姿势。有几个细节容易忽略。第一下载时的机器必须和目标机器有相同的操作系统、CPU 架构和 Python 版本否则拉下来的 wheel 用不了。第二如果目标机器上已经有一些依赖可能会和离线包里的版本冲突稳妥的做法是提前一天先在同样配置的机器上演练一遍。第三下载目录里的文件别改名pip 是靠文件名解析包信息的。7.4 排查速查表现象可能原因优先排查动作提示找不到模块装到了别的环境对比解释器路径与 pip 路径动态库加载失败缺运行时库或架构不符检查平台标识与运行库导入时 numpy 报错numpy 版本不兼容单独重装匹配版本的 numpy安装过程卡住网络访问不畅指定就近镜像源重试安装报权限错误杀软锁定或目录无写权限加白名单或换虚拟环境求解器对象为空后端名称拼写错误打印后端名并核对求解耗时异常长模型规模或参数设置问题打开日志看搜索过程这张表我建议你收藏一下。实际排查的时候九成的情况都落在前四行里按顺序试一遍基本都能解决。8. 工程化收尾把环境固定下来8.1 锁定版本别让环境自己漂移开发环境最怕的一件事是今天跑得好好的明天同事拉下来就报错。原因往往是某个包悄悄升了版本。解决办法是把依赖写进清单文件并且锁定版本。pip freeze requirements.txt这个文件会把当前环境所有包及版本记录下来。别人拿到之后pip install -r requirements.txt就能复现出一套几乎一模一样的环境。如果你的项目依赖比较复杂可以考虑用带哈希校验的锁定工具它会把依赖树完整展开并校验包的完整性更适合对可复现性要求高的场景。我个人在个人项目里的做法比较轻量只锁顶层直接依赖用兼容性约束而不是精确等于。比如写成ortools9.0,10这样小版本升级不会打破环境大版本升级时会提前知道要测试。团队协作的项目则倾向于精确锁定减少沟通成本。8.2 持续集成里的安装写法如果项目跑了自动化测试测试环境里的安装要注意两点一是使用无缓存安装确保每次都拉最新的匹配版本二是加超时和重试参数避免网络抖动导致构建失败。pip install --no-cache-dir --timeout 60 --retries 3 -r requirements.txt这几个参数都是我在实际构建里踩过坑之后加上去的。没有重试的那段时间构建失败率明显偏高而且失败原因还不好判断日志里就一句连接中断。另外自动化环境里建议固定 Python 镜像的版本别用浮动标签。用浮动标签的后果是某天上游更新了基础镜像你的构建突然就红了排查起来很浪费时间。8.3 多个版本共存的场景有些时候你确实需要同时保留两个不同大版本的 OR-Tools比如老项目在维护期不能升级新项目要用新特性。这件事用虚拟环境很好解决一个环境装一个版本需要哪个激活哪个。不建议在同一环境里用pip install ortoolsx.y反复覆盖虽然技术上可行但依赖树会越来越乱容易出现某些依赖留在旧版本上、某些已经升级的混合状态。这种状态下报的错往往很难解释。如果你用编辑器写代码记得检查它当前配置的解释器是不是你想的那个。我遇到过好几次明明激活了环境终端里能跑编辑器里却报错的情况最后发现是编辑器的解释器设置没跟着变。8.4 一条命令的极简路径回顾写到这里如果你只是想要最短路径把下面这段走完就够了python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate python -m pip install --upgrade pip python -m pip install ortools python -c from ortools.sat.python import cp_model; print(ok)四条命令加一条验证。我特意把这个顺序写成这样而不是直接一句pip install ortools是因为中间那两步建环境、升 pip花掉的时间不超过二十秒但能挡掉后面绝大部分麻烦。省这二十秒可能要花两小时去救环境这笔账怎么算都不划算。最后分享一个我个人的习惯。每次在新机器或新环境里装完 OR-Tools我都会把第 6.2 节那段小模型跑一遍把输出结果贴进项目的环境说明文档里顺便记下当时的版本号和时间。看起来很啰嗦但这个记录至少帮我省过三次时间一次是服务器环境迁移后行为变了靠对比版本号找到了原因一次是同事复现不了我的结果一看版本差了一个大版本还有一次是升级之后某个参数默认值改了翻记录才发现。另外OR-Tools 的版本迭代比较活跃遇到问题的时候除了搜报错信息也值得去翻一翻对应版本的发布说明很多行为变化都会在那里写清楚。比起在论坛里翻半天不知道有没有用的帖子这条路通常更直接。