ZVT 项目研究站 · 快速入门

ZVT Python 快速入门：装完 5 分钟拿到第一条 A 股数据

这一页只解决一件事：把 ZVT 装起来并查到第一条 A 股数据。不需要先理解因子与策略，只要按下面四步走完，你就能确认「环境对不对、数据源通不通」。所有命令都来自官方 README，每一步都写明预期输出与失败时的检查点——本站没有在本机运行 ZVT，所以不给运行截图，只给可复现的命令与判断标准。

直接看 5 分钟四步先确认 Python 版本口径

官方依赖：19 项钉版本Python 要求：>=3.9, <4依据 v0.13.5（2026-09-18 采集）

四步：环境 → 安装 → 写一条 → 查出来

建环境venv / conda，Python 3.9–3.12

装框架pip install -U zvt

写一条Stock.record_data(provider="em")

查出来query_data(index="code")

据官方 README 的安装与数据章节自绘（非官方流程图）；命令与参数名逐字取自 README 示例。

Environment

先选环境：三种建法对照，别直接装进系统 Python

ZVT 的 requirements.txt 钉死了 19 个依赖的版本，装进系统解释器会连带改动你已有的 pandas / numpy / SQLAlchemy。先建隔离环境再装。

方式	命令	适用场景	注意点
标准库 venv	`python -m venv .venv` 后激活（Windows 用 `.venv\Scripts\activate`，macOS/Linux 用 `source .venv/bin/activate`）	单项目、只想跑数据与因子	不跨项目共享依赖，最干净
conda	`conda create -n zvt python=3.11` 后 `conda activate zvt`	本机已用 conda 管理科学计算环境	conda 装的是解释器，ZVT 仍用 pip 装
已有虚拟环境复用	直接在该环境里 `pip install -U zvt`	已经把量化依赖集中在一个环境里	装之前先记录现有 pandas / numpy / SQLAlchemy 版本，便于回滚

版本红线：setup.py 与 PyPI 都要求 >=3.9, <4，按 README 里写的 3.8 会直接被 pip 拒绝安装（官方五处材料口径不一致，详见安装页的四份材料对照表）。建议直接用 3.10 或 3.11：既满足下限，也避开 3.12 与个别钉版本依赖的边界情况。

5 minutes

四步拿到第一条 A 股数据

每一步都给出命令与「怎么判断成功」。第四步结束之前不要急着写因子——先确认这条链路是通的。

装框架
```
python3 -m pip install -U zvt
```
说明：README 给出的唯一安装命令。预期输出：pip 拉取 zvt 0.13.5 与 19 个钉版本依赖并成功安装；若报 Could not find a version that satisfies the requirement zvt，先看你的解释器版本是不是低于 3.9。
确认装到了哪个解释器
```
python -m pip show zvt
```
说明：多环境机器上最常见的失败是「装到了 A 环境、在 B 环境里 import」。预期输出：显示 zvt 的版本与安装位置，路径应落在你刚激活的那个虚拟环境里。
写第一条数据：A 股标的清单
```
from zvt.domain import Stock

Stock.record_data(provider="em")
```
说明：这是 README 的第一条数据命令，不带 code 就是全市场，第一次跑会慢一些。预期输出：终端出现抓取日志，数据写进本地库（默认在 zvt_home/data 下）。若长时间无响应，先怀疑配置文件里默认打开的本地代理。
查出来验证
```
df = Stock.query_data(provider="em", index="code")
print(df)
```
说明：查询打在本地库上，不再联网。预期输出：一张以 code 为索引的 DataFrame，包含 entity_id、code、name、list_date 等列。README 示例里 A 股清单打印出 4136 行——那是当年的快照，你自己跑出来的行数才是当前值。

想再往前一步：把「清单」换成「某只股票的日线」只改一行——Stock1dHfqKdata.record_data(code='000338', provider='em')，再 query_data 就是一张价格表。表名怎么选（周期与复权）见「K 线与复权」页。

看 K 线表名与复权口径看取数与查询参数全表

Where to run

Jupyter、VSCode、命令行：三种运行方式的差异

ZVT 本身与编辑器无关，但环境解释器的选择会直接决定「能不能 import 到」。

运行方式	怎么用	适合	注意点
命令行 / REPL	激活环境后直接 `python` 或写脚本运行	首次验证、批量写库	写库是长任务，放脚本里比放 REPL 里稳
Jupyter Notebook	先在该环境里 `pip install ipykernel`，再选对应 kernel	边取数边看 DataFrame 的探索式研究	kernel 选错会 import 失败；长任务会阻塞 notebook
VSCode	命令面板选 Python 解释器指向 `.venv`	写策略与调试	左下角解释器与终端里 `pip` 用的解释器必须是同一个
定时脚本（crontab / 任务计划）	用绝对路径调用虚拟环境里的 python	日常增量更新	要写全解释器路径与工作目录，否则找不到包

Troubleshooting

第一条数据拿不到：按这个顺序查

下面六项覆盖「装完了却取不到数据」的绝大多数情况。前两项来自官方配置文件，后四项是通用排查面。

现象	最可能原因	怎么查	处理方向
import 就失败	装到了另一个解释器	`python -m pip show zvt` 看路径	切到正确解释器，或在该环境里重装
请求长时间无响应	`config.json` 默认开启本地代理 `127.0.0.1:1087`	打开框架配置文件看 http_proxy / https_proxy	按本机网络改或清空
某些 provider 报鉴权错误	该源需要账号（如聚宽的 `jq_username` / `jq_password`）	打印 `Stock.provider_map_recorder` 看这家源是否在列	换无账号源（em / eastmoney / sina / exchange）先跑通
写库到一半中断	全市场数据量大、被限流或网络抖动	看 `log_path` 下的日志原文	改小批次重跑（增量更新不会重复拉已入库的部分）
数据写进去了但查不到	查询条件或时间口径不对	先不带 filters 查一次，再加条件	参考取数页的 query_data 参数表
磁盘占用异常	分钟级或 tick 数据 + 多标的	看 `data_path` 目录大小	先小样本验证，再决定要不要全量

数据通了之后，先去哪一页

下一步取决于你要做的事。三条路各自的第一页如下。

要选股 / 算因子

先看「因子与选股」：data_df → factor_df → result_df 三层怎么组织，以及财务因子要用到的 report_period 与 report_date 时间口径。手上有因子后，务必再过一遍「点时数据与未来函数」。

要写策略 / 回测

先看「策略与回测」：StockTrader.on_time 与 trade_the_targets(due_timestamp, happen_timestamp)。信号能跑出来不等于回测可信，成交假设那一步在「从信号到可信回测」页。

要先把数据搞干净

先看「A 股数据避坑」：停牌、涨跌停、ST 退市、动态股票池、缺失与重复记录——这些官方不会替你处理，但会直接决定回测数字真假。抓问题要趁早。

看因子与选股看点时数据与未来函数看 A 股数据避坑

FAQ

快速入门常见问题

命令与参数以官方 README 为准；涉及运行结果的问题，本站都会说明证据缺口。

ZVT 到底是 Python 库还是软件？

是一个 Python 库（pip install -U zvt），装好后额外提供两个自带入口：zvt 命令起 Dash 界面、zvt_server 起 FastAPI 服务。它不是装完就能用的桌面软件，数据要靠你自己通过 provider 获取。

没有编程基础能用吗？

不太适合。ZVT 的使用方式是在 Python 里写代码：取数、查询、算因子、写策略。如果你只想查行情或看看指标，可以先走免部署的对话式技能路线（见「对比」页），需要可复现的因子研究时再回来搭环境。

5 分钟真的能跑通吗？

在环境已经就绪（Python 3.9–3.12 + 能联网）的前提下，安装与第一条查询本身只需几分钟；真正耗时的是数据量——全市场写库可能要跑很久。所以建议第一次先传 code 只写一只股票，确认链路后再放开。

要装数据库吗？

不需要额外装数据库服务：框架用 SQLAlchemy 把数据写成本地文件库，路径由 zvt_env 的 zvt_home / data_path 决定（详见取数与查询页）。要备份或迁移，把整个目录搬走即可。

Windows 上有特别要注意的吗？

三点：①激活虚拟环境用 .venv\Scripts\activate；②配置文件里 qmt_mini_data_path 默认写的是一个 Windows 路径样例，用到实时行情时要改成本机实际路径；③文档里的 git clone git:// 走 9418 端口，国内常被阻断，换 https://。

本站为什么不给安装成功的截图？

因为本站没有在本机安装运行 ZVT，任何「运行截图」都会是伪造的。所以这里只给官方命令、参数名与判断标准；ZVT 与 EasyClaw 也无已证实集成。