RQAlpha 项目研究站 · 安装与数据

RQAlpha 安装与数据：pip 装框架、download-bundle 取数据

两条命令就能进入回测状态：pip install rqalpha 装框架，rqalpha download-bundle 下载官方免费提供的日级别数据包（股票、常用指数、场内基金、期货），bundle 默认落在 ~/.rqalpha。官方强烈建议在虚拟环境里安装，并把「安装失败」的排查前置到首次运行之前。

下一步：运行策略先看数据边界

安装方式：PyPI（建议虚拟环境）数据：免费 A 股日线，月更依据官方 install 文档（2026-09 核验）

建虚拟环境
venv / conda

pip install
rqalpha

rqalpha version
验证安装

download-bundle
取可用数据

依据官方 install 文档整理的安装顺序示意；非官方流程图。

Environment

环境与版本要求

以下来自仓库 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 需编译工具链

查看许可与数据边界

Install

安装四步与验证

命令来自官方安装文档；国内网络慢时可按官方建议换用镜像源。

从零到可运行

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 依赖 numpy/pandas 的特定区间（见上表），与机器上已有科学计算环境混用最容易出问题。

Data

回测数据的三条获取路径

这一节是本项目与其他框架差别很明显的地方：数据默认由官方准备好，也可换成你自己的。

路径	命令/方式	覆盖范围	更新节奏
官方免费数据包	`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 ...——下载和运行两处的路径必须一致，否则运行时会读不到数据。

update-bundle 的前置条件：官方文档要求先安装 RQData 包、获取使用权限，并用米筐提供的配置脚本把 license 写入环境变量；不满足这些条件时，走 download-bundle 即可，不要反复重试更新命令。

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`	可同时开两类账户；只想用一个就只填那一项

下一步：运行策略

Troubleshooting

安装与数据排查表

问题与处理方式整理自官方安装文档的 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 后再试每日更新

FAQ

常见问题

必须先下载数据包才能跑回测吗？

跑官方示例时需要。官方流程是「装框架 → 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 环境，有别的方式吗？

若只是想做策略层面的研究与指标计算，可先看对比页列出的 EasyClaw 技能路线（quant-analyst 覆盖回测与风险指标建模、akshare-finance 覆盖 A 股行情数据）；但那不是本项目的运行环境。

这些步骤能保证回测结果可信吗？

不能。数据口径、复权方式、撮合规则与参数选择都会影响结果；本站只整理官方流程与边界，不对任何策略的历史表现或未来收益作承诺。