默认配置里开着本地代理
src/zvt/config.json 的 http_proxy 与 https_proxy 默认值是 127.0.0.1:1087。本机没有跑代理时，取数请求会连不上——这是「装完了但什么都取不到」最常见的原因，处理方式见报错页的排查表。
ZVT 项目研究站 · 安装与版本口径
ZVT 怎么安装：先解决「到底要哪个 Python 版本」这个官方自己没统一的问题
ZVT 的安装命令只有一行——python3 -m pip install -U zvt；真正让人卡住的不是命令，而是官方五处材料对 Python 版本的说法互不一致：setup.py 与 PyPI 写 >=3.9, <4，README.md 写 3.8，README-cn 写 3.6，ReadTheDocs 安装页写 3.7 与 3.8。本页把五处原文并列，并说明为什么执行时应该以 setup.py 为准。
五处材料，三个不同的 Python 下限
setup.py>=3.9, <4
PyPI<4, >=3.9
README.mdpython>=3.8
README-cnpython>=3.6
docs/install3.7 and 3.8
Version evidence
五处材料对 Python 版本的说法，逐条摆出来
这不是本站的推测，而是官方仓库里同时存在的五种写法。做环境规划前先把这张表看完，比装完再报错省时间。
| 出处 | 原文写法 | 类型 | 该怎么用 | 注意点 |
|---|---|---|---|---|
setup.py | python_requires=">=3.9, <4"， classifiers 列出 3.9 / 3.10 / 3.11 / 3.12 | 打包元数据 | 执行口径：pip 会按它做兼容性判断，装不上就是装不上 | 它才是安装时真正生效的约束 |
| PyPI 项目页 | requires_python: <4, >=3.9 | 发布元数据 | 与 setup.py 一致，可用来确认二手教程是否过期 | PyPI 的 license 字段是空的，许可信息只看 classifier 与仓库 LICENSE |
README.md（英文，开发段） | set up virtual env(python>=3.8) | 说明文字 | 参考，不要照做 | 按它用 3.8 会与 setup.py 的 >=3.9 冲突 |
README-cn.md | virtual env(python>=3.6) | 说明文字 | 参考，不要照做 | 中文 README 比英文版更旧，这一处差异最容易被国内教程抄走 |
docs/source/install.rst | “Officially Python 3.7, and 3.8.” | 文档站页面 | 参考，不要照做 | ReadTheDocs 上能直接搜到这一句，和 0.13.x 的实际要求已经脱节 |
结论：以
setup.py 的 >=3.9, <4 为准，用 3.9 到 3.12 之间的版本。低于 3.9 时 pip 会直接拒绝安装而不是降级——这是版本口径不一致最容易造成的误解。若官方后续修改，以仓库当前文件为准。Install paths
三条官方安装路径：装库、装源码、装开发环境
三条路径的用途不同，选错会多花时间：只想调用 API 用第一条，要改源码用第二条，要跑测试用第三条。
路径一 · 直接用 PyPI 上的包（README 推荐）
python3 -m pip install -U zvt说明：官方 README 的第一条命令，没有其他前置步骤。预期输出：pip 拉取 zvt 0.13.5 及其 19 个钉版本依赖；若当前解释器低于 3.9，会在这里因为
requires_python被拒绝。路径二 · 从源码安装（docs 安装页）
git clone https://github.com/zvtvz/zvt.git cd zvt python -m pip install .说明：需要改源码或跟进 master 时用。预期输出：以本地目录为源安装，版本号取自
setup.py的 0.13.5；文档站上那条git clone git://用的是 git 协议（默认端口 9418），国内网络常被阻断，建议改用https://。路径三 · 开发环境（README 开发段）
pip3 install -r requirements.txt pip3 install pytest pytest ./tests --ignore=tests/recorders/说明：想跑测试或贡献代码时用。预期输出：
tests/api、tests/contract、tests/factors、tests/ml、tests/trader、tests/utils下的用例运行；--ignore=tests/recorders/必须带上，因为 recorder 用例依赖真实数据源与凭据。
额外一步（REST 路线）：README 的 REST API 章节要求另外装
uvicorn——它不在 requirements.txt 的 19 项里，跑 zvt_server 前要补 pip install uvicorn。Dependencies
19 项钉版本依赖与它们带来的环境风险
requirements.txt 把每个依赖都钉死了版本。好处是可复现，代价是你的环境里如果已有不同的 pandas 或 numpy，装 zvt 会连带改动它们。
| 依赖 | 钉住的版本 | 为什么值得注意 | 装之前建议 |
|---|---|---|---|
pandas / numpy | 2.2.3 / 2.1.3 | 量化研究环境里最常见的主依赖，版本冲突会牵连整个环境 | 用独立虚拟环境，不要装进系统解释器 |
SQLAlchemy | 2.0.36 | 本地存储层；1.x 与 2.x 的写法差异大，与其它项目的库不兼容 | 确认本机没有 1.4 时代的代码依赖同一环境 |
dash / plotly / dash-bootstrap-components / dash_daq | 2.18.2 / 5.13.0 / 1.3.1 / 0.5.0 | zvt 命令的界面依赖这一组；只做数据与因子时其实用不到 | 不需要界面时可评估精简安装 |
fastapi / fastapi-pagination / orjson | 0.110.0 / 0.12.23 / 3.10.3 | REST 服务依赖；uvicorn 不在清单里，要单独装 | 只跑 zvt_server 时记得补 uvicorn |
scikit-learn | 1.5.2 | 机器学习模块（zvt.ml）依赖 | 与其它机器学习环境共用时注意冲突 |
jqdatapy / eastmoneypy | 0.1.8 / 0.2.0 | 聚宽与东财的数据封装，说明 provider 是靠这些第三方包取数的 | 聚宽一侧还需要账号密码，见数据源页 |
apscheduler | 3.10.4 | 定时任务依赖，对应 tasks 里的 runner | 长期运行建议交给系统计划任务而不是这个库 |
First run
装完之后先跑这四步验证，再动真数据
按官方材料的入口顺序验证，能把「装错了」和「配置错了」这两类问题分开。
确认装上了、版本对
python -c "import zvt; print(zvt.__version__ if hasattr(zvt,'__version__') else 'ok')"说明：只要能导入就说明
requires_python这一关过了。预期输出：打印 ok（或版本号）；报ModuleNotFoundError说明装到了另一个解释器里。起 Dash 界面
zvt说明：README 的「Main ui」路径。预期输出：服务起在本机 8050 端口，浏览器打开
http://127.0.0.1:8050/；注意当前入口文件只注册了factor一个标签页，看不到更多模块是正常的。起 REST 服务并看接口文档
pip install uvicorn zvt_server说明：需要先补 uvicorn。预期输出：8090 端口服务与
http://127.0.0.1:8090/docs；官方在api-tests/目录里放了可导入的.http样例（股票池、标签、因子、事件四组）。试一条最简单的取数
from zvt.domain import Stock Stock.record_data(provider="em")说明：这是 README 的第一条数据命令。预期输出：标的清单写入本地库（默认落在
zvt_home/data）；若卡住不动，先怀疑config.json里默认打开的本地代理，排查见报错页。
证据边界：以上四步是官方材料给出的路径与预期，本站没有在本机执行过（ZVT 与 EasyClaw 无已证实集成，本站也未安装 ZVT），因此不提供任何运行截图或实际输出。
Decision
四种安装场景，各自该怎么装
同一行命令在不同场景下的推荐做法不同，这张表把决策摆出来。
| 你的场景 | 推荐做法 | 理由 | 注意点 |
|---|---|---|---|
| 只想调用 API 研究因子 | 独立虚拟环境 + pip install -U zvt | 不污染系统解释器，也不需要 dash 那一组之外的额外动作 | 把虚拟环境的 Python 定在 3.10 或 3.11，避开最低版本边界 |
| 机器上已有一套量化环境 | 新建虚拟环境，不要往现有环境里装 | zvt 钉死了 pandas / numpy / SQLAlchemy 的版本 | 装之前记录现有版本，便于回滚 |
| 要改源码或跟进 master | clone 后 pip install .，不要用 pip install -U zvt | PyPI 包是发布快照，master 才包含最新改动 | README 的 Declaration 明确不保证向后兼容，改源码要有版本管理 |
| 要跑测试或做二次开发 | requirements.txt + dev.txt / docs.txt | 仓库把开发与文档依赖拆成了独立文件 | 测试命令必须带 --ignore=tests/recorders/ |
Platform notes
Windows 与国内网络下的四个已知摩擦点
这几条都能在官方文件里找到依据，但官方没有把它们放在一起提醒。
QMT 路径写死在配置里
同一个配置文件里 qmt_mini_data_path 的默认值是 D:\qmt\userdata_mini，只有一个 Windows 路径样例。用实时行情前要先把这项改成本机实际安装路径，并且先拿到 QMT 授权。
文档里的 git 协议在国内常被阻断
ReadTheDocs 安装页给的克隆命令是 git clone git://github.com/...，走 9418 端口。国内网络下大概率超时，换成 https://github.com/zvtvz/zvt.git 即可。
文件里带中文路径要留意编码
ZVT 的本地存储与导出都会写到磁盘，Windows 中文环境下的日志与导出文件可能出现编码问题。官方未给出 Windows 专属说明，遇到时以官方 issue 与源码为准。
FAQ
安装与版本口径常见问题
回答以官方仓库文件为准；凡涉及本机运行结果的问题，都会说明证据缺口。
到底该用哪个 Python 版本？
用 3.9 到 3.12 之间（推荐 3.10 或 3.11）。setup.py 与 PyPI 一致地要求 >=3.9, <4，这是安装时真正生效的判断；README 与文档页里写的 3.6/3.7/3.8 是过期说明。以仓库当前文件为准。
为什么按 README 用 3.8 会失败？
因为 pip 会读 setup.py 的 python_requires，3.8 不满足 >=3.9 会直接拒绝安装，而 README 的开发段仍写着 3.8。这是官方材料内部不一致造成的时间差，不是你的环境有问题。
装完命令找不到怎么办？
先确认装到了哪个解释器：用 python -m pip show zvt 看位置，再用同一个解释器的 Scripts（Windows）或 bin（macOS/Linux）目录确认 zvt、zvt_server、zvt_export 三个入口存在——它们由 setup.py 的 console_scripts 生成。
一定要装 dash 那一组依赖吗？
不一定。dash、plotly、dash-bootstrap-components、dash_daq 只服务于 zvt 命令的界面；只用数据与因子层时可以不要界面。但如果你用 pip install -U zvt 安装，这些依赖会一起装进来，官方没有提供精简安装选项。
装完就能取到 A 股数据吗？
不一定。取数能否成功取决于三件事：本机网络与代理配置、所选 provider 是否需要账号（聚宽需要，东财与新浪多数不需要）、以及数据源的可用性。默认配置里的代理值就是第一个要检查的地方。另外实时行情还需要 QMT 授权。
有 Docker 镜像吗？
仓库里没有 Dockerfile 或 compose 文件，只有两个 GitHub Actions 工作流（构建与打包）、build.sh 与 init_env.sh。想要容器化需要自己写，官方没有提供。
本站为什么不给安装成功的截图？
因为本站没有在本机安装运行 ZVT，任何「运行截图」都会是伪造的。页面只描述官方命令、官方路径与源码里能核实的事实；ZVT 与 EasyClaw 也没有已证实集成。要验证效果请在自己的环境按上面三步试。