Install Microsoft Qlib 0.9.7: Deploy Guide

Green pip install. Red first workflow. With Microsoft Qlib the damage usually isn’t the install line – it’s the dead official data blob (HTTP 409), importing while your shell sits inside the cloned repo, or a mirror that handed you a package literally named qlib. Below is how to get 0.9.7 to the point where qrun does something real.

Qlib is Microsoft Research’s open-source AI quant stack (arXiv:2009.11189): data → models → backtest, plus RL-style decision nesting. Stable PyPI build as of the Aug 15, 2025 tag: pyqlib 0.9.7. Docs main branch builds as 0.9.8.dev11 – don’t mix those numbers when you debug.

System requirements for Qlib 0.9.7

No hard RAM/disk floors in the official docs. Plan for multiple GB anyway once CN bins and feature cache land. Linux is the path of least pain; Windows and macOS are supported.

Python 3.8-3.12 show up as supported for pip and source on the GitHub README. Cython/LightGBM outside conda? Missing headers. That’s why the docs lean on conda so hard.

Install guides rot in public. A command that worked in a 2023 blog can still exit 0 today and leave you with empty calendars – not because you typed wrong, but because the data plane moved and nobody updated the screenshot.

Official download sources

• Code & releases: https://github.com/microsoft/qlib
• Stable package: pip install pyqlib → PyPI pyqlib
• Docs: qlib.readthedocs.io
• Docker: pyqlib/qlib_image_stable:stable on Docker Hub
• Community CN bins (needed while the official blob stays off): chenditc/investment_data releases

Install Microsoft Qlib step by step

Fresh conda env. Name it anything.

conda create -n qlib python=3.10 -y
conda activate qlib
pip install --upgrade pip
pip install pyqlib

That should resolve 0.9.7 plus the usual stack (lightgbm and friends per current packaging). Verify later. Don’t celebrate the Successful install line.

Source install (dev / main branch)

pip install numpy
pip install --upgrade cython
git clone https://github.com/microsoft/qlib.git
cd qlib
pip install . # or: pip install -e ".[dev]"

Apple Silicon + LightGBM often wants OpenMP before the build:

brew install libomp
pip install .

Docker (cleanest path)

docker pull pyqlib/qlib_image_stable:stable
docker run -it --name qlib-dev -v "$PWD":/app pyqlib/qlib_image_stable:stable

Miniconda image, pyqlib already on PATH. Mount notebooks/configs on /app. Compressed amd64 size sits around 900+ MB (Docker Hub listing; may shift).

Pro tip: Never keep cwd on the cloned qlib/ repo root when you import. Initialization docs are blunt: importing from inside the repository directory breaks path resolution. cd ~ or a separate project folder first.

First-time configuration and data

Official Azure public data is off (security policy) as of the current README. Old get_data.py hits on the blob come back HTTP 409. Use the community dump the README itself links:

mkdir -p ~/.qlib/qlib_data/cn_data
wget https://github.com/chenditc/investment_data/releases/latest/download/qlib_bin.tar.gz
# README samples lean on strip-components=1; nested top folder? try 2
tar -zxvf qlib_bin.tar.gz -C ~/.qlib/qlib_data/cn_data --strip-components=1
rm -f qlib_bin.tar.gz

Minimum init – from any directory except the qlib source tree:

import qlib
from qlib.constant import REG_CN
qlib.init(provider_uri="~/.qlib/qlib_data/cn_data", region=REG_CN)
print(qlib.__version__)

Redis defaults to 127.0.0.1:6379. Down? Qlib skips cache. No hard fail. Match region to what you actually unpacked (CN vs US).

Some tars hide an extra directory level. If calendars/ and features/ are not sitting directly under cn_data, re-extract with --strip-components=2 (scripts/README shows that variant). Silent mismatch: init “works”, every feature query comes back empty.

You did everything “right” and the calendar is still blank. That gap – green install, hollow data – is where most first-week time goes. Not model tuning. Path layout.

Verify the install works

python -c "import qlib; print(qlib.__version__)"
# expect 0.9.7 (or 0.9.8.dev* from main)

python -c "
import qlib
from qlib.constant import REG_CN
from qlib.data import D
qlib.init(provider_uri='~/.qlib/qlib_data/cn_data', region=REG_CN)
print(D.calendar(start_time='2020-01-01', end_time='2020-01-10')[:3])
"

If you still have the scripts tree:

python scripts/check_data_health.py check_data --qlib_dir ~/.qlib/qlib_data/cn_data

Only after data lands, smoke a workflow. Directory must not be the qlib clone:

qrun examples/benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

(Assumes a clone somewhere with examples on disk; the Docker image already ships them.)

Common install errors and fixes

1. HTTP 409 / Public access is not permitted on qlibpublic.blob.core.windows.net – official dataset disabled. Community qlib_bin.tar.gz above.
2. No matching distribution for pyqlib – Python <3.8, offline index, or you typed pip install qlib. Real name: pyqlib. Some mirrors ship an empty stub called qlib; pin PyPI if needed.
3. FileNotFoundError: …/VERSION.txt after mixing setup.py install with a later pip install . – burn the env, reinstall with one method.
4. LightGBM / wheel build fails on Mac – brew install libomp, then rebuild.
5. AttributeError: No such registered in self._config inside joblib workers on backtest (reported on 0.9.7, e.g. Windows/Python 3.10) – config re-init in child processes; track the issue or try a thread backend while a fix lands.
6. Import path weirdness right after clone – leave the repo directory before import qlib.

Upgrade and uninstall

pip install -U pyqlib

Source/main:

cd qlib && git pull && pip install .

No formal migration script between 0.9.x minors for plain offline use. Re-run data health after big jumps. Stale experiments? Wipe mlruns/ or the expression cache dir – those linger.

Uninstall / cleanup:

pip uninstall pyqlib -y
# optional full wipe
rm -rf ~/.qlib
docker rm -f qlib-dev # if you used the container
docker rmi pyqlib/qlib_image_stable:stable

FAQ

Is pip install pyqlib enough to start modeling?

No. Package only. Without CN/US bins under provider_uri, data calls are empty – grab the community tar first.

Docker vs conda – which should I pick?

Docker when you want one pull and zero host fights (Mac OpenMP and header failures just disappear). Conda when you already live in notebooks, need GPU torch, or will hack Qlib with pip install -e .. Both are first-class.

Why does my calendar or instrument list disagree with old tutorial screenshots?

Community dumps merge vendors and fix delistings; Yahoo-style official dumps (when they worked) were imperfect by the authors’ own notes. Point-in-time rules and adjust methods drift across releases. Public bins = research starters, not production ground truth. The platform paper and docs both push you toward your own feed when the PnL has to be real.

Create the conda env → pip install pyqlib → drop qlib_bin.tar.gz into ~/.qlib/qlib_data/cn_data → three-line init + calendar check → one LightGBM qrun from outside the source tree.