Install Qlib v0.9.8 AI Quant Platform Guide

End state: Qlib answering import qlib, CN daily bars on disk, and a LightGBM workflow printing IC / return / drawdown. Target is tagged v0.9.8 (8 Oct 2026) from source, or current PyPI pyqlib 0.9.7 if you only need the stable wheel.

Qlib (Microsoft, MIT) wires data handlers, supervised/RL/dynamics models, backtest, and online serving into one path. This page is deploy → verify → fix only. No alpha theory tour.

System Requirements for the AI Quant Platform

README matrix: Python 3.8-3.12 on Linux (preferred), Windows, macOS (Intel and Apple Silicon). Conda/Miniconda is the boring choice that stops missing C headers from blowing up cython/tables builds.

Hardware rows above are community/secondary guidance (as of late 2026 DeepWiki-style summaries and issue threads), not a hard vendor SLA – treat them as planning floors.

Ever watched a bare pip env thrash for twenty minutes on native extensions, then die on a missing header? That wait is why the conda line exists. Not mystique. Just fewer 2 a.m. rebuilds.

Official Sources and Download

Grab code from microsoft/qlib. v0.9.8 (8 Oct 2026) hardens artifact loading and config-driven imports – security release, not a feature parade.

PyPI still lists stable pyqlib 0.9.7 as of the latest check; source or the v0.9.8 tag is how you get the newer guards. Install notes live on qlib.readthedocs.io. Background paper if you want the original framing: arXiv:2009.11189.

Docker image name you’ll actually type: pyqlib/qlib_image_stable:stable (or build with IS_STABLE=yes/no per the image docs).

Data reality check. Official hosted CN pack is temporarily disabled under a stricter data-security policy. README points at the community binary instead:

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
rm qlib_bin.tar.gz

Skip old get_data.py / legacy mirror links for CN – they 404 or hang for the same policy reason. One path. Use it.

Step-by-Step Installation

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

Stable wheel:

pip install pyqlib

v0.9.8 / source:

git clone https://github.com/microsoft/qlib.git && cd qlib
pip install . # pip install -e .[dev] if you want editable

Apple Silicon: brew install libompbefore source install. Without OpenMP, LightGBM wheels face-plant – README Mac tips and a pile of GitHub issues say the same thing. Windows: stay in conda; mixed pip/conda + Git Bash is where scipy DLLs go to die.

Docker:

docker pull pyqlib/qlib_image_stable:stable
docker run -it --name qlib-dev -v $(pwd):/app pyqlib/qlib_image_stable:stable

docker build --build-arg IS_STABLE=yes -t qlib:stable -f Dockerfile .

If an error looks cursed, diff your env against the repo CI workflows under .github/workflows. Most “mystery” breaks are version skew the CI already forbids.

First-Time Configuration and Data

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

v0.9.8 catch: loading older recorder artifacts, pickled models, or local .py config imports now wants an explicit trusted=True (API or CLI). Fresh training and plain data reads stay open. Read the artifact/config migration notes in the release docs before you hoist yesterday’s experiment store into production.

Verify the Install Works

python -c "import qlib; print(qlib.__version__)"

Expect 0.9.7 from pip, or 0.9.8 / a dev string from source. Used pure pip? Clone the repo anyway so examples/ exists.

cd examples
qrun benchmarks/LightGBM/workflow_config_lightgbm_Alpha158.yaml

Numbers on screen (IC, annualized return, max drawdown) = green light. Wrong version string or empty provider path = stop and fix before you touch YAML knobs.

Common Install Errors and Fixes

• Mac M-series LightGBM build fail – brew install libomp, then pip install . again.
• setuptools-scm LookupError / missing VERSION.txt – you installed from a zip or incomplete tree. Full git clone, then pip install -e . (issues #731, #1992 class).
• Windows scipy _iterative DLL load failed – new conda env; reinstall numpy/scipy there; don’t mix channels.
• Gym + NumPy 2.0 backtest crash – pin numpy<2 or move to gymnasium (community threads #1861 / #2018 territory).
• No matching distribution for pyqlib – confirm 3.8-3.12 and a platform wheel; otherwise source install.

Data 404/hang? You’re still on the disabled official pack. Community tar section above is the fix – don’t loop get_data.py.

Upgrade, Migration, Uninstall

pip install -U pyqlib refreshes the wheel line. For 0.9.8 guards: re-clone or check out the tag, then pip install .. Release notes call out the trusted=True behavior on old artifacts. Recent tags have not rewritten on-disk qlib bin layout in a breaking way.

pip uninstall pyqlib
# conda remove --name qlib --all
rm -rf ~/.qlib # optional data wipe
docker rm -f qlib-dev # if you used the container

Later rabbit holes: RD-Agent factor mining, custom converters, high-frequency nested execution – after this box actually runs.

First successful qrun feels oddly small. Then the question hits: which lever do you change first – labels, universe, or the model block inside that YAML? Pick one. Ship the diff.

FAQ

Does pip install pyqlib give me v0.9.8?

No. PyPI still ships 0.9.7 as of the latest check. Clone and pip install . (or checkout the v0.9.8 tag) for the security release.

Why does official data download fail and what do I use instead?

Hosted CN data is paused on Microsoft’s side for security-policy reasons. Same afternoon I hit the wall, the README already pointed at chenditc/investment_data’s qlib_bin.tar.gz. Extract with --strip-components=1 into ~/.qlib/qlib_data/cn_data, then qlib.init. US collectors/scripts are a separate path if you need them.

Can I run Qlib fully in Docker without local Python?

Yes – and no, you do not need a host venv “just in case.” Pull pyqlib/qlib_image_stable:stable, mount data + examples, extract the community tar inside the container, run qrun. Need main-branch code? Build with IS_STABLE=no. People assume Docker skips the trusted=True rules; it doesn’t. Artifact policy follows the Qlib version in the image, not where the process runs. docker start -i qlib-dev next time.