FinMarketPy / 安装与环境边界
finmarketpy 安装：先认清两条版本线，再按顺序装三个库
该库最容易踩的坑不是命令写错，而是装错了版本线：PyPI 上的 0.11.19（2025-03-10）解包后是扁平结构 finmarketpy/… + setup.py，而 GitHub master（2026-04-16 最后提交）已经改成 src/finmarketpy + pyproject.toml（hatchling 后端）+ uv.lock。两条线命令不同、目录不同、依赖声明也不同。另外 README 写 Python 3.10，而 pyproject.toml 与 PyPI 元数据都写 >=3.9——这一页把三处口径并列摆出来，不替你裁决，只给你核验命令。
pyproject.toml 与 PyPI 元数据）；示意非官方流程图，命令与版本以官方文档和你自己的安装结果为准。PyPI 发布版与 GitHub master 有什么区别
两边的差异不只在版本号，而在包结构、构建方式与依赖声明来源。选错线会导致「照着 README 找文件找不到」。
| 对比项 | PyPI 0.11.19（2025-03-10） | GitHub master（2026-04-16 最后提交） | 注意点 |
|---|---|---|---|
| 包内结构 | 扁平：finmarketpy/backtest/…、finmarketpy/curve/… | src/finmarketpy/backtest/…（PR #68 “Move finmarketpy package into src/ layout”） | 文档里看到的相对路径写法会不一样 |
| 构建与版本管理 | setup.py | pyproject.toml（hatchling 后端）+ uv.lock + Makefile；版本字段是占位 "0.0.0"（注释写明不要手改） | master 的版本号不再从 __version__ 一类静态字段读 |
| 依赖声明来源 | PyPI 元数据：blosc, chartpy, findatapy, matplotlib, numba, numpy<2, pandas>=1.5.3, scikit-learn, seasonal | pyproject.toml 的 dependencies（同一份清单）+ dependency-groups.dev（pytest / pre-commit / deptry / marimo） | 两边依赖清单一致，但 dev 依赖只出现在 master |
| 典型安装命令 | pip install finmarketpy | pip install git+https://github.com/cuemacro/finmarketpy.git | README 明说「better to get the newest version from repo, as opposed to releases」 |
| 体量（参考） | wheel 1.77 MB / sdist 2.02 MB | 仓库约 8 MB（GitHub API size） | 体积主要来自示例与图片，不在运行依赖上 |
| 适合谁 | 想用「发布版」对齐别人的文章与截图、要稳定可复现 | 想跟最新代码、要看 src/ 布局与新的开发流程 | 两者可以共存于不同虚拟环境，别混装 |
python -c "import finmarketpy, os; print(os.path.dirname(finmarketpy.__file__))"，路径里带 \src\ 说明是 master 线（源码安装/可编辑安装），不带则多为 PyPI 线。以你自己的输出为准。安装步骤怎么走：从环境自检到最小导入
下面每一步都给出命令、一句话说明与可核对的预期结果，命令全部来自官方 README 与 INSTALL.md。
先确认 Python 版本与虚拟环境
官方三处口径不一致，先看你自己的解释器：
python -V。建议建独立虚拟环境再装，避免和系统里的 numpy/pandas 打架（python -m venv .venv后激活）。预期：看到 3.9 及以上的版本号。装出图层：chartpy
pip install git+https://github.com/cuemacro/chartpy.git（或pip install chartpy走 PyPI 0.1.16）。预期：python -c "import chartpy; print(chartpy.__file__)"能打印路径。装取数层：findatapy
pip install git+https://github.com/cuemacro/findatapy.git（或pip install findatapy走 PyPI 0.1.42）。预期：import findatapy成功，且findatapy.market可导入。装本体：finmarketpy
pip install git+https://github.com/cuemacro/finmarketpy.git或pip install finmarketpy。官方要求这两个前置库先装好再装本体。预期：安装过程不出现依赖解析失败。最小导入自检
依次导入三个库并打印版本/路径：
import finmarketpy, findatapy, chartpy; print(finmarketpy.__file__, findatapy.__file__, chartpy.__file__)。预期：三条路径都来自你的虚拟环境（不是全局 site-packages）。初始化凭证（下一步之前必做）
技能侧改
marketconstants.py或新建marketcred.py；chartpy 侧chartconstants.py里配 Plotly key；findatapy 侧dataconstants.py或datacred.py。四条路线的取舍见数据源与凭证。跑官方最小示例
仓库
finmarketpy_examples/backtest_example.py用data_source='alfred'+ FRED/ALFRED 免费 key 取 G10 货币对日线，再跑 SMA(200) 回测。预期：先打印行情表尾部，再打印持仓最后一行，最后出图（无图说明 chartpy 引擎没配好）。完整链路见回测全链路。可选：装期权定价依赖
只有要用
curve/的 FinancePy 定价路径时才需要：pip install numba numpy scipy llvmlite ipython pandas prettytable，然后单独装pip install financepy==0.370 --no-deps。官方要求指定版本并加--no-deps，否则会和其它库的严格版本约束打架。
pip install -U --no-deps finmarketpy findatapy chartpy——这条命令同样来自官方 README，意思是「只换这三个包，不动 numpy/pandas 等依赖」，可以避免升级时把环境里其它库一起顶掉。Python 与依赖版本要求是什么：官方三处口径并列
这不是本站的推断，而是官方文件互相不一致；把三处都列出来，你才能在报错时对上号。
| 来源 | Python 要求 | 关键依赖约束 | 时效 | 注意点 |
|---|---|---|---|---|
| README「Requirements」 | Required: Python 3.10 | findatapy、chartpy 为必装 | 随 master 更新（README 最近一次改动为 partial Rhiza system，约 5 个月前） | 这是最早被搜索引擎收录的一句，容易与 pyproject 冲突 |
pyproject.toml（master） | requires-python = ">=3.9"（ruff target-version = "py39"） | numpy<2、pandas>=1.5.3、blosc、numba、scikit-learn、seasonal | master | 写 py39 但不代表作者在 3.9 上测过——README 仍写 3.10 |
| PyPI 0.11.19 元数据 | >=3.9 | 与 pyproject 同一份清单 | 2025-03-10 | pip 是拿这份元数据做依赖解析的 |
INSTALL.md | 正文仍在讲 Python 3.5/3.6/3.7 与 Anaconda py37class 环境 | 列的是 pip install arctic / blpapi / cufflinks 等旧组件 | 17 KB 的长文档，内容年代明显偏旧 | 这份文件不能当作当前版本的安装依据读，环境和依赖都已变化 |
numpy 必须 <2
这是硬约束，写在 pyproject 与 PyPI 元数据里。如果你的环境已经装了 numpy 2.x，pip 解析阶段就可能报冲突或把 numpy 降到 1.x，进而影响同环境里的其它库。稳妥做法是给该库单独一个虚拟环境。
pandas 有下限没有上限
声明是 pandas>=1.5.3，没有上限；而 0.11.19 的发布说明写的是 “Changed NumPy and Pandas versions”。pandas 大版本升级后出现 deprecation 报错时，先考虑换回与发布版接近的版本。
FinancePy 是可选项
README 记录：2025-03-08 把 FinancePy 变成可选依赖，2025-03-09 把它从 pyproject.toml 中移除。也就是说默认安装不会再带期权定价依赖，要用得自己按指定版本装。
Windows 上装要注意什么
官方 INSTALL.md 是 Windows 视角写的，但年代偏旧；下面把它仍然有效的部分和已经过时的部分分开列。
| 事项 | 官方说法 | 现状判断 | 你要做什么 |
|---|---|---|---|
| C++ 编译器 | INSTALL.md 要求装 Visual Studio / VC++ build tools，并提示可能需要把 C:\Program Files (x86)\Windows Kits\8.1\bin\x64 加进 PATH，以解决找不到 rl.exe 的编译错误 | 当时是为了编译 blpapi、arctic 等组件；这两个不是必装项 | 只有你要用 Bloomberg / arctic 时才需要，纯回测可以先跳过 |
| Anaconda 还是 venv | INSTALL.md 推荐 Anaconda + conda create -n cuemacro python=3.6 pip（强调必须带 pip，否则 pip 会装到全局） | conda 那个坑仍在，但版本号该按 pyproject 的 ≥3.9 起算 | 用 venv 最简单；用 conda 就带上 pip |
| 字体 | chartpy 的 matplotlib 默认字体是 Open Sans，需要自行下载安装，并删除 matplotlib 的字体缓存（如 fontList.py3k.cache） | 仍是有效提醒 | 如果出图报字体相关错误或中文变方块，按这条处理 |
| 安装目录 | INSTALL.md 未特别限制；但官方另在其它项目里提示避免过深路径 | Windows 长路径仍可能触发问题 | 装在盘根目录或较短的路径下更稳 |
| 依赖体积 | 三库的发布包：chartpy wheel 约 4.24 MB、findatapy wheel 约 1.85 MB、finmarketpy wheel 约 1.77 MB；依赖侧还有 numba / scipy 系 | 总体不算大，但 numba 与 matplotlib 会拉入不少体积 | 内网环境先备好 wheel 或配镜像 |
| 不装环境跑 | README 提供两个 mybinder 链接（backtest_example.ipynb、market_data_example.ipynb） | 需要能连到 mybinder.org，部分数据仍需 Quandl/FRED key | 只想先看一眼 API 长什么样时，这是最快路径 |
cufflinks、pip install arctic，都早于 2020 年的依赖重构（chartpy 已用 Plotly Express 替代 cufflinks）。它仍然是环境搭建思路的好参考，但版本号请以 pyproject.toml 与 PyPI 元数据为准。装完怎么确认「真的好了」
下面每一条都是一次性命令，输出的位置就是你下一步排错的依据。
| 检查项 | 命令 | 预期结果 | 不符合时先看哪一页 |
|---|---|---|---|
| 解释器版本 | python -V | 3.9 及以上（README 建议 3.10） | 报错与版本边界 |
| 三库是否都来自当前环境 | python -c "import finmarketpy, findatapy, chartpy; print(finmarketpy.__file__); print(findatapy.__file__); print(chartpy.__file__)" | 三条路径都在你的虚拟环境目录下 | 路径若指向全局 site-packages，说明虚拟环境没激活 |
| 是否 src/ 布局 | 看上一步 finmarketpy 的路径是否含 src | 含 src → master 线；不含 → PyPI 线 | 决定了你该按哪套目录找示例 |
| numpy 版本 | python -c "import numpy; print(numpy.__version__)" | 1.x（因为约束是 numpy<2） | 若为 2.x，说明依赖没解析干净 |
| 取数能否走通 | 用官方最小示例的 MarketDataRequest(data_source='alfred', …, fred_api_key=…) | 返回一张日期索引的行情表 | 返回空/报错 → 数据源与凭证 |
| 出图能否走通 | from chartpy import Chart, Style 然后 Chart().plot(df, style=Style(file_output='t.png')) | 本地生成图片文件 | 无图 → 检查 chartpy 引擎与字体配置 |
安装常见问题
命令与前置以官方 README、pyproject.toml 为准；本站未实机安装验证。
到底该 pip install finmarketpy 还是装 git+ 版本？
看你想要什么。PyPI 线拿到的是 0.11.19（2025-03-10），结构是扁平的 finmarketpy/…；git+ 线拿到的是当前 master，已是 src/finmarketpy/… 布局并带 pyproject.toml。官方 README 自己建议优先用仓库版本（“better to get the newest version from repo”）。如果你在读别人的文章或教程，建议先用 PyPI 版本对齐结构，避免「按文档找不到文件」。以官方仓库现状为准。
为什么一定要先装 chartpy 和 findatapy？
因为这两个是该库的必装依赖：取数靠 findatapy，出图靠 chartpy。官方 README 特意提醒「装本体之前先确保这两个（以及其它依赖）已装好」。正常情况 pip 会连带装上，但在网络不稳或离线环境里，先把两个前置装好能显著减少失败点。
Python 3.9 到底行不行？
官方给出的是三个不同答案：README 写 Required: Python 3.10，pyproject.toml 写 >=3.9，PyPI 元数据也写 >=3.9，而 INSTALL.md 还停留在 3.7 时代。本站不做裁决：能用 3.10+ 就用，这也是官方 README 的写法；确实要降到 3.9 时，请以你自己的运行结果为准，并优先按 报错页的方法定位。
装完提示 numpy 版本冲突 / 被降级，正常吗？
正常，这是 numpy<2 这条硬约束造成的。它会阻止在同一个环境里保留 numpy 2.x。最省事的做法是给该库单独一个虚拟环境，别和需要 numpy 2 的库共用。若你发现环境里的 numpy 已经被降级，说明之前有其它库依赖它——回到干净环境重装比反复升降级更省时间。
没有 Redis / MongoDB，能装能跑吗？
能。Redis 只影响缓存：没有它会打印 Couldn't push MarketDataRequest 并回退为每次都去外部取数，功能不受影响（这条来自 findatapy README）。MongoDB/arctic 只在你要用数据库存行情时才需要，官方还写了 write_engine='arctic' 这类常量，默认值要改成你自己的环境。
不想装环境，能不能直接看？
可以：README 提供两个 Binder 链接，在浏览器里直接跑官方 notebook；另外也可以走免部署的 免部署技能路线先拿数据与结论。两条都不是该库的本地安装方式，具体差别在顶部导航的「对比」页。