← All tools · Guides

Qlib: install, China A-share data, and a first Alpha158 + LightGBM run

Hands-on. Install Qlib, load China A-share data, and run a first machine-learning stock-selection model.

How to choose: The first successful Qlib run is four steps: a separate Python 3.12 environment, pip install pyqlib, the community China A-share dataset, and one qrun. The official dataset is paused, so older get_data tutorials no longer download it. If the job is to score a basket of stocks every day and buy the top ranks, use Qlib. If the job is when to buy and sell one or two stocks from a moving average or an indicator, use backtrader. Qlib does not send orders to a broker. Paper-trade first, then a broker terminal such as QMT or PTrade. Comparing nine backtesting frameworks is a different article. This page only installs Qlib and runs Alpha158 plus LightGBM.

Who it is for: Someone who already writes a little Python and wants to score a basket of China A-shares with a machine-learning model, then buy the top ranks, on their own computer. The path is Python 3.12, the community A-share files, one qrun, and how to read IC, excess return, and maximum drawdown. A run on 21 Oct 2026 used Windows 11, Python 3.12, and pyqlib 0.9.7.

Who it is not for: Someone who wants to know when to buy and sell a single stock. backtrader is the shorter path for that. Someone who wants Qlib to place live orders in a brokerage account. It does not connect to the account. This page is not the tool-order guide, not the site FAQ, and not the nine-framework comparison. The official dataset is paused, so an old download command will not fetch it.

The same walkthrough in Chinese is Qlib: install, A-share data, and a first model. A single-stock moving-average example is the first backtrader strategy. Comparing nine frameworks is how to choose a backtesting framework. That comparison is not this article.

This site has no commercial relationship with Microsoft, the Qlib project, or the authors of the community data. The commands and numbers below are from the run recorded on the Chinese page on 21 Oct 2026 (Windows 11, a 16-core CPU, Python 3.12.13 in a uv virtual environment, pyqlib 0.9.7, mlflow 3.17.2). This English page did not re-run them. Another machine or another data file will take a different time and print different numbers. Catalog entry: Qlib.

01 · What Qlib is

Qlib is Microsoft's open-source AI quant platform. The licence is MIT. The work it is built for sits in front of the backtest: prepare data, compute factors, train a model, score stocks, and buy the high scores. The backtest is the last step of that pipeline.

It fits this question: each day, inside a basket of stocks, which names are most likely to outperform. If the question is when to buy and sell one stock, backtrader is the shorter path. The same first strategy in Chinese is backtrader (Chinese).

02 · Install: start with Python 3.12

The official README lists Python 3.8 through 3.12, on Linux, Windows, and macOS. Python 3.13 and 3.14 are not on that list. The test machine had only 3.14, so uv created a 3.12 virtual environment and left the system Python alone:

uv venv --python 3.12 qlib-env
qlib-env\Scripts\activate          # macOS / Linux: source qlib-env/bin/activate
uv pip install pyqlib

Without uv: install 3.12 from python.org, then py -3.12 -m venv qlib-env and pip install pyqlib. Same idea.

• Version: pip installed 0.9.7 (released Aug 2025). GitHub already has v0.9.8 (8 Oct 2026). Its release note says that tag is a source package only, and the change is security hardening. The 0.9.7 that pip installs is enough to finish the steps below.
• Mac M1: the README warns that compiling LightGBM on an M1 can fail. Install brew install libomp first.
• The example config is not in the pip package. Download it from GitHub. Section 04 has the URL.

03 · China A-share data: the official set is paused

This is the step that now stalls most people. The Qlib README says that, because data-security policy is stricter, the official dataset is paused. It recommends the community project investment_data. The get_data download in older tutorials no longer fetches the official files.

investment_data publishes a tarball on GitHub each day. The licence is Apache-2.0. Its notes say the file merges several sources, including Wind and Caihui (those two only through 2019), Tushare, and AKShare, and that prices are adjusted. The 21 Oct 2026 file, after extraction, looked like this:

• Dates from 4 Jan 2000 through 21 Oct 2026, 6,170 stocks, including names that have been delisted and names on the Beijing Stock Exchange.
• Each stock has open, high, low, close, VWAP, volume, amount, the change, and an adjustment factor.
• Membership lists for the CSI 300, CSI 500, CSI 800, CSI 1000, and the whole market.

On Windows, in PowerShell, using the curl.exe and tar that shipped with that Windows 11 machine:

curl.exe -L -o qlib_bin.tar.gz https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz
mkdir $HOME\.qlib\qlib_data\cn_data
tar -zxf qlib_bin.tar.gz -C $HOME\.qlib\qlib_data\cn_data --strip-components=1

On macOS or Linux, the commands from that README:

wget https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz
mkdir -p ~/.qlib/qlib_data/cn_data
tar -zxvf qlib_bin.tar.gz -C ~/.qlib/qlib_data/cn_data --strip-components=1

The archive is more than 500 MB. Unpacked, it is about 700 MB. The 21 Oct 2026 release itself was 543 MB. The project's notes say to check the download first. The same release page has qlib_bin.manifest.json, which records the archive's SHA256. On Windows, Get-FileHash qlib_bin.tar.gz -Algorithm SHA256 should match that file before you extract. The copy used for this walkthrough matched on size and on SHA256.

04 · The first run: one qrun

Download the official example workflow_config_lightgbm_Alpha158.yaml (the v0.9.7 tag, matching the pip install). Line 2, provider_uri, is the data directory. The default is ~/.qlib/qlib_data/cn_data, which is where the previous step extracted the files. If the data sits somewhere else, or the run says it cannot find the data, replace that value with the full path. The test run did that. Then:

$env:MLFLOW_ALLOW_FILE_STORE="true"      # macOS / Linux: export MLFLOW_ALLOW_FILE_STORE=true
qrun workflow_config_lightgbm_Alpha158.yaml

The first line is a pitfall from the actual run. Without it, mlflow in a fresh environment (Qlib uses it to store the experiment; the installed release was 3.17.2) exits with "filesystem tracking backend is in maintenance mode". The error message itself names this environment variable as the bypass. With it set, reading the data, training, and the backtest took about four minutes on a 16-core CPU. The experiment log is the mlruns folder in the directory where you ran the command.

What that example config does, in plain language:

• Universe: CSI 300 constituents. The benchmark is the CSI 300 index.
• Three time slices: 2008 through 2014 train the model, 2015 through 2016 tune it, and Jan 2017 through Aug 2020 are the exam (the backtest). The model does not see the exam period while it trains.
• Model: LightGBM, a tree model. The inputs are the 158 factors in the next section. The output is a score for each stock.
• What it trades: hold the 50 highest scores. Each day, replace at most 5 names whose rank has fallen. The official docs put the turnover of that rule at about 20% a day.
• Cost assumptions: 0.05% to buy, 0.15% to sell, a minimum of 5 yuan per order. A move beyond 9.5% is treated as a limit-up or limit-down that cannot be traded. Fills use the close.

That last line is the example's assumption, not today's real schedule. China's securities transaction stamp tax has been charged at half the previous rate since 28 Aug 2023 (a Ministry of Finance notice). Commission and the transfer fee differ by broker. Use the schedule from the broker where the account is opened. To bring the backtest closer to that bill, change open_cost, close_cost, and min_cost in the config.

05 · What Alpha158 is

Alpha158 is the factor set that ships with Qlib: the clues the model sees. Counted from the installed 0.9.7 source, there are exactly 158. All of them use open, high, low, close, and volume. None of them use financial statements.

• 9 candlestick features: for example the body as a fraction of the open, ($close-$open)/$open, and how long the upper and lower shadows are.
• 4 same-day prices: open, high, low, and VWAP, each divided by the close so they are relative.
• 145 rolling features: 29 formulas times 5 windows (5, 10, 20, 30, and 60 days). Examples: the N-day return, the N-day average, N-day volatility, where the price sits inside the N-day range, price-volume correlation, and the share of up days.

They do not guarantee a useful signal. They give the model a ready starting point. To use your own factors, replace the Alpha158 handler in the config, or add to it.

06 · How to read the result

The end of the log prints several numbers. The table is that run, next to the same model on Qlib's benchmarks page (the mean of 20 random seeds):

• What an IC near 0.05 means: a correlation tops out at 1. An IC of 0.05 is a weak same-direction relationship. It is almost useless for one stock. It can show up only if many names are held together and the rule is repeated for a long time.
• The annualized figure is a sum, not compound growth: in the Qlib source, annualized return is the average daily return times 238. That is a simple sum, not compounding, so it is not the annualized return people usually quote.
• The numbers are excess: both the return and the drawdown are the part above the CSI 300. Over the same period the CSI 300's own maximum drawdown was -37%. Whether the strategy itself lost money still depends on adding the index move back.
• A gap versus the published numbers is normal: a different data file and a different random seed both move the result. IC was almost the same as the published figure, and the return was higher. That gap was not taken apart line by line. Do not read it as "the community data is better."

07 · Make it yours

• Extend the dates: the example stops at Aug 2020, and the community data already reaches Oct 2026. Move end_time and the three segments forward to see later years. The train, tune, and exam slices must not overlap.
• Change the universe: the benchmarks page shows the CSI 500 switch. Replace csi300 with csi500, and the benchmark SH000300 with SH000905.
• Change the model: each folder under examples/benchmarks is one model (XGBoost, MLP, LSTM, and others), with its own config. Point qrun at another file to compare. The README warns that dependencies differ. TFT, for example, supports only Python 3.6 and 3.7. Read that model's folder before you switch.

08 · Pitfalls

• mlflow says "filesystem tracking backend is in maintenance mode": set MLFLOW_ALLOW_FILE_STORE=true before the run. See section 04.
• The Python is too new: 3.13 and 3.14 are outside the supported range. Install fails, or the run fails in a way that is hard to read. Use 3.12.
• An old tutorial cannot download the data: the official dataset is paused. Use the community files in section 03.
• Do not load a config or a model you have not read: the v0.9.8 release notes tightened that restriction. On 0.9.7, run only config files you have read yourself.
• A kind backtest is not a profit: the exam period is only 2017 through 2020. Another market can look completely different. Real costs, market impact, and halts all make a live account worse than the backtest. Paper-trade first. The worked version is paper trading after a backtest. The same article in Chinese is in Chinese.

09 · What to read next

• To own the download and update it yourself: how to choose between Tushare and AKShare, and the hands-on download AKShare into SQLite. The same walkthrough in Chinese is in Chinese.
• Other open-source AI quant projects, besides Qlib: the project list. The same list in Chinese is the Chinese project list.
• To send the selected names to a live account: how to choose between QMT and PTrade. The same guide in Chinese is QMT and PTrade (Chinese). The wider platform comparison, which is a different article, is how to choose a quant trading platform.

This is not investment advice. A machine-learning result on past data is not a future return. Qlib's features, versions, and licence follow its own notice, and so do the community data files.