RQAlpha 项目研究站 · 安装与数据
RQAlpha 安装与数据：pip 装框架、download-bundle 取数据
两条命令就能进入回测状态：pip install rqalpha 装框架，rqalpha download-bundle 下载官方免费提供的日级别数据包（股票、常用指数、场内基金、期货），bundle 默认落在 ~/.rqalpha。官方强烈建议在虚拟环境里安装，并把「安装失败」的排查前置到首次运行之前。
venv / conda
rqalpha
验证安装
取可用数据
依据官方 install 文档整理的安装顺序示意；非官方流程图。
环境与版本要求
以下来自仓库 pyproject.toml 与官方安装文档，装之前先对齐版本。
| 项目 | 要求 | 说明 |
|---|---|---|
| Python | requires-python >=3.8 | 分类器覆盖 3.8 – 3.14；用虚拟环境隔离依赖 |
| 数值栈 | numpy（3.11 及以下 <2.0；3.12+ 需 >=2.0）、pandas >=1.0.5, <3.0 | Python 版本不同，numpy 依赖区间不同，别硬锁旧版本 |
| 数据层依赖 | h5py、hdf5plugin | 数据包以 HDF5 形式存储，缺失会在读 bundle 时失败 |
| 指标与画图 | rqrisk >=1.0.10、matplotlib >=3.1.0、tabulate、openpyxl | 风险指标计算、plot 收益曲线、Excel 报告输出 |
| CLI 与配置 | click >=7.0.0、PyYAML、logbook、jsonpickle、simplejson | 命令行参数、config.yml 解析、日志与结果序列化 |
| 可选性能分析 | pip install rqalpha[profiler] | 逐行性能分析依赖 line_profiler；Windows 需编译工具链 |
安装四步与验证
命令来自官方安装文档；国内网络慢时可按官方建议换用镜像源。
从零到可运行
1. 创建并激活虚拟环境（python -m venv venv，Windows 用 venv\Scripts\activate）；
2. pip install rqalpha（官方文档给出的加速写法：pip install -i https://pypi.douban.com/simple rqalpha）；
3. rqalpha version 确认安装成功、版本号能打印；
4. rqalpha generate-config 在当前目录生成一份含全部默认项的配置模板，后续改参数不必猜字段名。
回测数据的三条获取路径
这一节是 RQAlpha 与其他框架差别很明显的地方：数据默认由官方准备好，也可换成你自己的。
| 路径 | 命令/方式 | 覆盖范围 | 更新节奏 |
|---|---|---|---|
| 官方免费数据包 | rqalpha download-bundle | 日级别：股票、常用指数、场内基金、期货 | 每月月初更新一次 |
| RQData 每日更新 | rqalpha update-bundle | 依赖 RQData 权限与 license 配置 | 每日盘后即时更新 |
| 自有数据源 | 实现数据层接口（docs 的 data_source / event_source 章节） | 自定：可接分钟级、可接其他市场 | 由你的数据管道决定 |
指定数据包存放位置
默认在 ~/.rqalpha。若想放到别处：下载时用 rqalpha download-bundle -d target_bundle_path，运行时也必须带上同一个路径 rqalpha run -d target_bundle_path ...——下载和运行两处的路径必须一致，否则运行时会读不到数据。
download-bundle 即可，不要反复重试更新命令。数据包与配置模板：容易踩的点
把配置项与数据包的关系理清，后面运行策略会顺很多。
| 配置项 | 作用 | 注意点 |
|---|---|---|
data_bundle_path | 数据包路径 | 默认空值即用 ~/.rqalpha；改过下载路径就必须同步改这里 |
auto_update_bundle | 回测中自动下载缺失的 bundle 数据 | 当前支持盘前集合竞价成交量、期货历史交易参数；默认关闭 |
auto_update_bundle_path | 自动下载数据的独立存放路径 | 不设置则复用 data_bundle_path |
frequency | 回测频率：1d / 1m | 官方明确：开源版本不提供分钟级数据源，选 1m 前先确认你有数据 |
market | 市场：CN / HK | 开启 HK 后回测将无法交易 A 股任何标的，二者不能同时用 |
accounts | 账户与初始资金：stock / future | 可同时开两类账户；只想用一个就只填那一项 |
安装与数据排查表
问题与处理方式整理自官方安装文档的 FAQ 章节。
| 现象 | 原因 | 处理 |
|---|---|---|
| pip 安装速度极慢或失败 | 默认源网络问题 | 按官方文档换国内镜像：pip install -i https://pypi.douban.com/simple rqalpha |
| 依赖冲突 / 装完导入报错 | 与系统 Python 里既有 numpy/pandas 版本冲突 | 改用虚拟环境重装（官方首要建议） |
| 性能分析不可用 | line_profiler 不随默认安装附带 | pip install rqalpha[profiler]；Windows 需先装 Visual C++ 编译工具 |
matplotlib 报 Python is not installed as a framework | 后端配置问题 | 新建 ~/.matplotlib/matplotlibrc 并写入 backend: TkAgg |
| macOS 找不到 bundle 文件 | Finder 默认隐藏以点开头的目录 | 终端开显示隐藏文件：defaults write com.apple.finder AppleShowAllFiles -boolean true ; killall Finder |
macOS 制图中文字体报 Operation not permitted | 系统 rootless 机制限制写系统目录 | 按官方 FAQ 处理权限；缺 wget/fontconfig 用 brew 安装 |
| update-bundle 一直失败 | 没有 RQData 权限或 license 未进环境变量 | 先用 download-bundle；确认权限与 license 后再试每日更新 |
pip install 到底装了什么：每个依赖负责哪一块？
依据仓库 pyproject.toml 的 dependencies 与 optional-dependencies 整理：RQAlpha 的取数、回测、指标、出图、报告这几条链路各由不同依赖承担。
| 依赖 | 在 RQAlpha 里干什么 | 缺失或版本不符的后果 | 注意点 |
|---|---|---|---|
numpy | 行情与净值计算的数组运算底座 | 导入即失败，回测无法启动 | 官方按 Python 版本分段：3.11 及以下用 <2.0.0、3.12 及以上用 >=2.0.0，换 Python 版本这条依赖会跟着换 |
pandas >=1.0.5,<3.0.0 | 取数接口返回的 DataFrame 与结果整理 | 取数结果无法处理，或与 3.x 不兼容 | 回测结果落盘后也常用 pandas 读回做二次分析 |
h5py + hdf5plugin | 读写 HDF5 格式的 bundle 数据包 | 数据下载成功、运行时却读不到 | 属于数据层依赖，缺了表现为「有数据但读不出来」 |
rqrisk >=1.0.10 | 回测结果里的风险指标计算 | 风险指标缺失或计算报错 | 官方单独维护的指标库，版本过低会缺指标 |
matplotlib >=3.1.0 | 绘制收益曲线（--plot） | 出图失败或无输出 | 无图形界面环境要改 backend，两个平台推荐值不同（见下方排查表） |
openpyxl | 生成 Excel 版回测报告 | Excel 报告生成失败 | 报告模板随包分发（包内含 report/templates/*.xlsx），不需要自己准备模板 |
PyYAML | 读取 config.yml / config.json | 配置文件不生效 | generate-config 生成的就是 YAML 模板 |
click >=7.0.0 | 命令行入口与参数解析 | rqalpha 子命令不可用 | run / download-bundle / generate-config 都经过它 |
logbook | 回测日志输出 | 日志缺失，出问题难定位 | -l verbose/info/warning/error 控制的正是它 |
jsonpickle + simplejson | 回测结果的序列化与 JSON 输出 | -o 落盘的结果文件读写异常 | 与结果文件格式绑定，不要随意升降级 |
tabulate | 在命令行打印指标表格 | 回测结束看不到摘要表 | 只影响展示，不影响计算与落盘结果 |
python-dateutil + six | 日期解析与兼容工具 | 交易日历与日期字符串处理异常 | 一般不显式安装，pip 会自动带上 |
methodtools / filelock / typing-extensions | 方法与文件锁、类型标注支持 | 并发或缓存相关行为异常 | 批量回测时结果文件的互斥依赖 filelock |
line_profiler（可选） | 逐行性能分析（rqalpha[profiler]） | 默认不安装，性能分析功能不可用 | 只在需要性能分析时装，Windows 还要准备编译工具链 |
pyproject.toml 里，其中 numpy 直接按 Python 版本分成两段区间。若把 numpy 手工锁在 1.x 又升到 Python 3.12，问题会出现在导入阶段而不是回测阶段；配合虚拟环境安装能把这类冲突限制在项目内。bundle 下载之后放在哪、运行时怎么被读到？
官方 install 文档给出的是一条「下载 → 指定路径 → 运行时对齐路径」的链；下面把每条命令与预期结果摊开。
五步确认数据真的可用
1. rqalpha download-bundle —— 下载官方免费日级别数据包（股票、常用指数、场内基金、期货）。（预期输出：命令行显示下载过程，数据包落在默认目录 ~/.rqalpha）
2. rqalpha download-bundle -d D:\rqdata\bundle —— 把数据换到空间充足的盘位。（预期输出：数据写入该目录，目录下出现 bundle 文件）
3. rqalpha run -d D:\rqdata\bundle -f strategy.py -s 2016-01-01 -e 2016-12-31 --account stock 100000 —— 运行时必须带同一个 -d。（预期输出：回测日志与指标摘要；不带 -d 时会回到默认目录找数据）
4. dir %USERPROFILE%\.rqalpha（Linux / macOS 用 ls ~/.rqalpha）—— 直接看目录确认数据落地。（预期输出：列出 bundle 相关文件与目录）
5. rqalpha generate-config —— 需要一份可改的配置就先生成模板。（预期输出：当前目录出现 config.yml）
~/.rqalpha/ 下创建 config.yml 作为默认配置文件；其二，-d 管的是「数据放在哪」，配置里的 data_bundle_path 管的是「运行时去哪读」，两处不一致时以命令行传参为准。| 情形 | 表现 | 处理 | 注意点 |
|---|---|---|---|
下载时用了 -d，运行时没带 | 运行时按默认目录找不到数据 | 运行时补上同一个 -d | 下载与运行两处的路径必须一致 |
配置里 data_bundle_path 与下载目录不一致 | 配置写了却读不到数据 | 把两处改成同一路径 | 命令行传参会覆盖配置文件里的同名项 |
| 策略里用相对路径读自有数据文件 | 换个目录运行就报错 | 用绝对路径，或通过 context.config.base.strategy_file 定位策略所在目录 | RQAlpha 是读取策略代码执行的，实际当前路径是执行 rqalpha 命令的路径 |
| macOS 在 Finder 里找不到 bundle | 以点开头的目录默认隐藏 | 打开显示隐藏文件：defaults write com.apple.finder AppleShowAllFiles -boolean true ; killall Finder | 数据一直在盘上，只是没显示出来 |
| 数据下载成功但读取报错 | 通常缺 h5py / hdf5plugin | 按依赖清单补齐后重试 | bundle 以 HDF5 存储，读取依赖这两个包 |
| 想改官方示例却找不到 examples | 示例被装进 Python 环境，路径较复杂 | 把 examples 目录复制到顺手的位置再改 | 官方 install 文档 FAQ 第 5 条专门提示过这一点 |
无图形界面环境 --plot 没有输出 | matplotlib backend 不合适 | Linux 可写 backend: Agg 到 ~/.config/matplotlib/matplotlibrc | 官方 FAQ 给 macOS 的值是 TkAgg，两个平台别照抄 |
常见问题
必须先下载数据包才能跑回测吗？
跑官方示例时需要。官方流程是「装框架 → download-bundle → run」；如果你实现了自有数据源接口，也可以绕开 bundle，但那属于进阶用法（见 docs 的 data_source / event_source 章节）。
免费数据包多久更新一次？
官方说明：免费提供日级别数据，每个月月初更新。需要每日盘后即时更新，要配合 RQData（安装 rqdatac 包并配置 license）使用 update-bundle。
数据包会占多大空间？要放哪？
官方未给出固定体积承诺，实际取决于覆盖范围与时间跨度。默认路径 ~/.rqalpha；体积敏感或盘位有限时用 -d 指定到数据盘，并在运行时传入同一路径。
Windows / macOS / Linux 都支持吗？
框架是纯 Python 包，三个平台都能装；官方 FAQ 针对 macOS 与 Windows 各列了具体坑（matplotlib 后端、中文字体权限、line_profiler 需要编译工具）。
不想装 Python 环境，有别的方式吗？
若只是想做策略层面的研究与指标计算，可先看对比页列出的本机技能路线（quant-analyst 覆盖回测与风险指标建模、akshare-finance 覆盖 A 股行情数据；RQAlpha 与 EasyClaw 无已证实集成）；但那不是 RQAlpha 的运行环境。
这些步骤能保证回测结果可信吗？
不能。数据口径、复权方式、撮合规则与参数选择都会影响结果；本站只整理官方流程与边界，不对任何策略的历史表现或未来收益作承诺。