QuantLib · Install & verify

QuantLib 安装教程：pip、conda 与 C++ 源码编译怎么选

QuantLib 本体是 C++ 库，日常调用走的是 Python 绑定 QuantLib-Python。本页先把三条安装路线（pip wheel / conda / CMake 编译）的代价摆清楚，再给出本站真实跑过的安装记录、四步验收命令与「装完怎么确认真的能算」的检查清单，最后说明哪些问题上安装、哪些问题其实在别处。

跑通一次期权定价看错误与排查

实测环境：QuantLib 1.43 / Python 3.11.9 / Windows安装耗时：单条 pip 命令是否需要编译器：走 wheel 时不需要

选路线wheel / conda / 源码

建环境venv 隔离

装包pip install QuantLib

验收版本 + 日历 + 子模块

安装四步：先选路线，再隔离环境，然后装包，最后做验收。本站实测走的是 wheel 路线（无需 Boost 与编译器）；源码编译路线在本机未实测。示意图非官方安装流程图。

测试版本QuantLib 1.43（PyPI wheel `quantlib-1.43-cp39-abi3-win_amd64.whl`，12.9 MB）Python 版本3.11.9（Windows，官方 CPython；wheel 为 cp39-abi3）最后核验2026-10-09（安装与验收命令在本机实跑）安装方式独立虚拟环境（venv）+ pip，未改动系统 Python依赖要求仅需 pip/wheel；无需 Boost、无需编译器（走 wheel 路线）验收方式`QuantLib.__version__`、日历清单、日期上限与四个子模块导入可直接复现是（命令、预期输出与验收脚本均在本页）本站实测范围仅安装与导入验证；未在本站编译 C++ 源码、未接行情数据

实测版本QuantLib 1.43（pip wheel，12.9 MB）

路线wheel / conda / 源码编译

验收7 项检查清单

证据等级本站实测（安装与导入命令实跑）

Three routes

三条安装路线怎么选：代价全在依赖上

同样能 `import QuantLib`，三条路线的准备工作量差很多。下面这张表把「要装什么、谁来编译、适合谁」逐列摆开，判断标准只有一个：你要不要读或改 C++ 源码。

三条主要路线的代价对照（wheel 与编译两条路线的差异，主要就是「谁替你编译」）
安装路线	装什么	是否需要编译器 / Boost	适合谁	注意点
pip 安装官方 wheel	Python 绑定二进制包（本机实测 `quantlib-1.43-cp39-abi3-win_amd64.whl`，12.9 MB）	都不需要	用 Python 做定价、建模、教学与研究的人	wheel 覆盖的 Python 版本与平台有限，装不上就得换路线
conda 安装	conda 渠道的二进制包（版本号可能滞后于 PyPI）	都不需要	已在用 conda / Anaconda 管理环境的人	版本与 PyPI 不一定同步，先看清装到的版本号
C++ 源码编译	库源码 + CMake + 满足版本要求的 Boost + C++ 编译器	都需要，且版本要匹配	要读源码、改引擎、做 C++ 集成或做二次开发的人	Boost 与编译器版本不匹配是最常见的失败点；本站未实测此路线
用官方 Release 二进制	官方发布页提供的预编译包	视包而定	不想自己编译、又需要 C++ 库的人	以官方下载页当前提供的包为准，不要照抄旧教程里的路径
面向 Excel / R 的封装层	不是 Python 绑定，而是另一套接口层	各自依赖不同（通常要一个已装好的库本体）	需要在 Excel / R 里调用的场景	它们不是 Python 绑定；不要把三者混为一谈
容器镜像	别人构建好的镜像	不需要	要可复现环境或做部署的人	镜像内的版本与来源要自己确认，本站未实测

先分清三层东西：① C++ 库本体；② 官方 SWIG 绑定（Python 侧，pip 包名就是它）；③ 面向 Excel 与 R 的封装层。本站讨论的是第 ② 层「在 Python 里 import 并使用」这条路线。三者的概念与包界限以官方文档为准。

Measured install

本站实测：一条 pip 命令装完，装到的是 1.43

下面是本机真实执行的命令与真实输出（Python 3.11.9 / Windows）。注意 wheel 文件名里的 `cp39-abi3` ——它决定了「哪些 Python 版本能用同一个 wheel」。

安装命令与实测输出（Chat: 已完成）> python -m venv qlenv
> qlenv\Scripts\python.exe -m pip install --upgrade pip wheel
> qlenv\Scripts\python.exe -m pip install QuantLib

Collecting QuantLib
  Downloading quantlib-1.43-cp39-abi3-win_amd64.whl.metadata (1.9 kB)
Downloading quantlib-1.43-cp39-abi3-win_amd64.whl (12.9 MB)
   ---------------------------------------- 12.9/12.9 MB 1.2 MB/s  0:00:11
Installing collected packages: QuantLib
Successfully installed QuantLib-1.43

> qlenv\Scripts\python.exe -c "import QuantLib as ql; print(ql.__version__)"
1.43

实测记录：这台机器上的安装事实（版本、体积、ABI 标签）
观察项	本机实测值	怎么读这个值
下载的 wheel 文件	quantlib-1.43-cp39-abi3-win_amd64.whl	版本号 1.43；win_amd64 表示 64 位 Windows
wheel 体积	12.9 MB	含 C++ 核心与绑定的二进制；不含行情数据
ABI 标签	cp39-abi3	面向 CPython 3.9 及以上的稳定 ABI，所以 Python 3.11 也能装同一个 wheel
安装结果	Successfully installed（包名 + 版本 1.43）	只装了一个包，不附带任何第三方依赖
运行时版本号	1.43	`ql.__version__` 是验收第一步，务必先确认它
是否改了系统 Python	否（装在独立 venv 里）	隔离环境便于多版本并存与随时删除
装完是否需要联网	否	库本身不含行情，定价用的曲线与波动率由你给

Platforms

Windows / Linux / macOS 差在哪：只看有没有现成 wheel

三条路线里，wheel 路线的差别其实就是「有没有人替你建好对应平台的包」。下面这张表说明判断顺序：先试着装 wheel，装不上再考虑编译。表里不确定的地方如实标注为未核实，不替官方下结论。

平台差异的判断顺序：先试 wheel，再看 conda，最后才考虑自行编译
平台	wheel 路线的典型情形	装不上时怎么办	需要额外准备什么	注意点
Windows（本机实测）	pip 直接装到 win_amd64 的 wheel 并成功	装不到对应版本时改用 conda 或官方预编译包	无（走 wheel 时）	本站实测 Python 3.11.9 装 cp39-abi3 wheel 成功
Linux	发行版与 Python 版本不同，命中情况差别较大（本站未实测）	优先试 conda，其次 CMake 编译	编译路线需要 Boost 与 C++ 工具链	不要照抄旧教程里的二进制源与固定路径，以官方安装说明为准
macOS	同为 Unix 系，命中情况与 Python 版本相关（本站未实测）	优先试 conda，其次 CMake 编译	编译路线需要 Xcode 命令行工具与 Boost	Apple Silicon 与 Intel 的包不同，先确认机器架构
其他 Python 版本	wheel 的 abi3 标签决定可用窗口	换一个受支持的 Python 版本，往往比折腾编译省事	无	版本组合以 PyPI 上该版本的文件列表为准

关于 cp39-abi3：cp39 是最低 CPython 版本，abi3 表示使用稳定 ABI，因此一个 wheel 能覆盖 3.9 及以上的若干 Python 版本——这正是本机 Python 3.11 能装它的原因。反过来，如果你用的 Python 比 wheel 记录的最低版本还老，就需要换成更新的 Python 或走编译路线。标签含义以 Python 官方打包文档与 PyPI 文件列表为准。

Steps

六步装完并验收：每步都有可核对的输出

顺序照做即可。第 5、6 步最关键——很多人装完只看「没有报错」，但真正的验收是「能打印出预期值」。下面每一步都给出本机实测过的输出形态。

1. 建一个隔离环境

用 python -m venv qlenv 建虚拟环境，后续所有命令都用 qlenv\Scripts\python.exe（Linux/macOS 是 qlenv/bin/python）调用，避免污染系统 Python。预期结果：目录下出现独立的环境文件夹。

2. 先升级 pip 与 wheel

执行 python -m pip install --upgrade pip wheel。新版 pip 对 wheel 的处理更稳；本机实测这一步静默完成。

3. 装上包

执行 pip install QuantLib。本机实测下载 quantlib-1.43-cp39-abi3-win_amd64.whl（12.9 MB），末行输出 Successfully installed QuantLib-1.43。

4. 打印版本号

执行 python -c "import QuantLib as ql; print(ql.__version__)"，本机输出 1.43。这一步能过，说明二进制已正确加载。

5. 检查日期与日历能力

打印 ql.Date.todaysDate() 与本机可用的日历类清单。实测本机可用：China、Germany、Japan、TARGET、United Kingdom、United States、WeekendsOnly；日期上限 `ql.Date.maxDate()` 实测是 2199-12-31。

6. 跑一次最小定价

建一个欧式看涨并打印 NPV。本站实测参数（S=K=100、r=5%、vol=20%、一年期、Actual/365 Fixed）下 NPV 为 10.4681483852——能打印出这个量级的数字，才算「装对了并且能算」。

Acceptance

装完验收清单：7 项全过才叫装好

把验收拆成可勾选的 7 项。任何一项对不上，先查环境（是不是用错了 Python 解释器），再查版本，最后才怀疑安装本身。下表「实测值」列是本机 QuantLib 1.43 的真实输出。

验收清单：本机 QuantLib 1.43 的真实输出（可作为你自查的对照基准）
验收项	怎么查	本机实测值	对不上时的含义
包已安装	`pip show QuantLib` 或再次 pip install	Successfully installed QuantLib-1.43	可能装到了另一个环境里
运行时版本	`ql.__version__`	1.43	版本与教程不符：先对齐版本再照抄代码
日期能力	`ql.Date.todaysDate()`	随运行日期变化（本站运行日为 2026-10-09）	打印异常说明解释器或包损坏
日期上限	`ql.Date.maxDate()`	December 31st, 2199	上限用于判断极端估值日是否会越界
日历可用	打印可用日历清单	China / Germany / Japan / TARGET / United Kingdom / United States / WeekendsOnly	缺项说明装的不是完整绑定的包
计息约定可用	打印含 Actual / Thirty 的类名	Actual360、Actual364、Actual36525、Actual365Fixed、Actual366、ActualActual、Simple、Thirty360、Thirty365	缺项会影响债券与曲线计算
最小定价可跑	算一个欧式看涨的 NPV	10.4681483852（S=K=100, r=5%, vol=20%, T≈1.00273973）	能导入但算不出：检查是否误用了其它库的同名对象

Checklist

装之前先确认这 6 件事，能省掉大部分返工

下面的检查按「出错概率从高到低」排序。前两项几乎能解释安装阶段八成的问题，后几项决定了你后面能不能顺利跑通定价。

安装前检查清单：前两项能解释大部分安装期问题
先确认	为什么重要	怎么确认	不问清会怎样
用的是哪个 Python 解释器	多环境机器上 pip 与 python 常指向不同解释器	打印 `sys.executable` 与 `sys.version`	装到了另一个环境，运行时报「找不到模块」
Python 版本与 wheel 是否匹配	wheel 的 cp39-abi3 标签决定了可用窗口	`python -V` 与 PyPI 文件列表对照	pip 会去尝试源码构建，然后失败
是否需要 C++ 源码能力	决定了选 wheel 还是编译	问自己：要不要读或改 C++	为了「以后可能用得上」先装整套编译链，白花时间
是否需要多版本并存	研究常要对照两三个版本的结果	用独立 venv 或 conda 环境	升级后旧脚本算出的数字变了却查不出原因
估值日怎么设	库默认用运行当天，回测结果会天天变	显式设置 `ql.Settings.instance().evaluationDate`	每天跑同一段代码得到不同数字
数据从哪来	它不含行情数据，只有计算框架	确定曲线、报价、波动率的来源与口径	装完发现「没有数据可用」，误以为是安装问题

看错误与排查看估值日与约定

Environments

多版本并存、升级与降级：把环境当成实验条件

定价结果会随版本与约定变化，所以「装了什么版本」本身就是要记录下来的实验条件。下面这张表给出仍在本机验证有效的操作方式，以及每步的连带影响。

环境管理操作表（本站实测的环境为 venv + pip）
要做的事	怎么做	连带影响	注意点
看当前版本	`python -m pip show QuantLib`	无	同时能看到装在哪条路径下
升级到更新版本	`python -m pip install --upgrade QuantLib`	数字可能与旧版本有差异	脚本里写死的结论要重新验一遍
固定到某个版本	`python -m pip install QuantLib==1.43`	结果可复现	团队协作时把版本写进依赖清单
降级排查	装回旧版本后再跑同一段代码	可判断问题是否由版本引起	降级前记录当前版本号与出问题的脚本
多版本并存	每个版本一个 venv（本机实测用 venv 隔离）	环境干净、互不影响	注意别让 pip 与 python 指向不同环境
彻底卸载重装	先卸载再重装，必要时删掉环境目录重建	回到干净状态	卸载前确认没有别的项目在用这个环境

和排查页的分工：本页只负责「装得上、导得进、算得出」；如果你已经能 `import QuantLib` 但结果不对（价格为 0、曲线报错、指标异常），那属于计算结果问题，去看错误与排查，那里按报错原文分类。

China notes

中国市场要先想清的三件事（装完也不会自动解决）

很多中文教程把「装好库」当成中国市场可用的前提，实际上安装只是第一步。下面这张表说明安装能给你什么、不能给你什么，避免装完才发现缺关键一环。

安装能给什么、不能给什么（中国市场相关的常见误解）
你想要的	安装能提供吗	实际要自己补的	注意点
人民币债券定价框架	能（提供债券、日历、计息、曲线等计算组件）	按发行文件确定付息频率、计息口径、结算天数	它不含中国市场的估值规则与惯例
中国交易日历	能（实测可用 China.SSE 与 China.IB 两类）	确认用交易所日历还是银行间日历	两者假期不同，选错会让现金流日期错开
中债 / 交易所行情数据	不能	自行导入报价、曲线节点或成交数据	库不含数据源与接口，数据口径与日期必须自己记录
中国市场计息约定	不能直接提供	按市场规则选定 DayCounter 并统一口径	实测本机枚举里没有 China 专用计息口径
实时行情与交易接口	不能	另找数据与交易通道	它是定价与风险计算库，不做行情与下单
中文文档	不能	对照官方英文文档与仓库示例	以官方文档为准，第三方教程的版本可能已过时

FAQ

常见问题

装 QuantLib 需要先装 Boost 和 Visual Studio 吗？

走 pip 的 wheel 路线不需要。本站实测在 Windows + Python 3.11.9 上，pip install QuantLib 直接装到 quantlib-1.43-cp39-abi3-win_amd64.whl（12.9 MB）并输出 Successfully installed QuantLib-1.43，全程没有编译、没有 Boost。只有走 C++ 源码编译路线时才需要 CMake、Boost 与 C++ 编译器，这条路线本站未实测。依赖要求以官方安装说明为准。

为什么我装完 import QuantLib 报「找不到模块」？

先查是不是用错了 Python 解释器：多环境机器上 pip 与 python 常指向不同环境。核对 sys.executable 与 python -m pip show QuantLib 的安装路径是否在同一个环境里，再用 ql.__version__ 确认能打印出 1.43。如果仍然失败，按错误与排查里「安装与版本类问题」的判据逐项核对。以官方安装说明为准。

wheel 文件名里的 cp39-abi3 是什么意思？我的 Python 3.11 为什么能装？

cp39 表示最低面向 CPython 3.9，abi3 表示使用稳定 ABI，所以同一个 wheel 能覆盖 3.9 及以上的多个 Python 版本——本机实测 Python 3.11.9 就是装了这个文件。标签的确切含义以 Python 官方打包文档为准；具体某个版本有没有对应文件，看 PyPI 上该版本的文件列表。

装完就有行情数据了吗？

没有。它是定价与风险计算库，不含行情数据、不含数据源接口，也不做下单。本机验证的验收项里只有版本号、日期能力、日历清单与最小定价，没有任何数据接口。定价用的曲线、波动率与报价都要自己准备，并记录数据日期与口径。以官方文档为准。

能不能同时装两个版本对照结果？

可以，用独立环境隔离：每个版本一个 venv（本机实测就是这样做的），或者用 conda 环境。这样升级或降级不会影响正在用的脚本。注意别让 pip 与 python 指向不同环境——这是多环境机器上最常见的失误来源。版本升级后，之前写死的数字要重新验证一遍。

装完之后第一步该跑什么？

先跑本页第 6 步的最小定价（S=K=100、r=5%、vol=20%、一年期、Actual/365 Fixed），本站实测 NPV 为 10.4681483852。能打印出这个量级的数字，说明安装、导入与定价链路都是通的；再去期权定价页看完整示例与 Greeks。两页的数字都来自同一套实测参数，可以直接对照。

想用 EasyClaw 免部署做量化研究，还需要装 QuantLib 吗？

看你做什么。要自己写 C++/Python 定价代码、改定价引擎、做曲线构造，就需要本地安装并自己维护环境。只想用一句话发起量化研究任务（数据查询、指标计算、策略回测），可以走 EasyClaw 的免部署路线。两者是独立的路线：QuantLib 与 EasyClaw 无已证实集成。路线对比见顶部导航「对比」页。

安装失败、报 DLL 或版本不匹配的错，去哪看？

本页只覆盖「装得上、导得进、算得出」；具体的报错原文、成因与处置办法统一放在错误与排查页，那里按报错文本分类，并标注哪些是本机实测到的真实报错。命令与版本以官方安装说明为准。