Qbot: a local-first quant research stack built on qlib, backtrader and vnpy

The gap Qbot targets: research code and order routing in one process

Most retail quant work splits into two halves that never meet. A notebook holds the factor study, and a separate broker terminal holds the orders. Qbot's stated goal is to close that loop locally: the README describes it as providing a full cycle from data acquisition through strategy development, backtesting, simulated trading and finally live trading, with the GUI as the front end and a backend handling data processing and trade scheduling in an event-driven flow. The repository diagram is explicit about what sits underneath. It labels Qbot as the sum of a strategy layer, a backtest system and automated trading, with quant.ai pointing at qlib and deep learning strategies, BackTest pointing at backtrader and easyquant, and the trading leg pointing at vnpy, pytrader and pyfunds. Visualisation runs through quantstats for the dashboard. The intended user is named in the README as the retail trader, and the project asks for only a little Python and a little trading experience. That framing matters: this is a platform for someone who will read the code, not a managed product.

Layered abstraction: data and strategy as intermediate representations

The first highlight in the README is a modular layered design covering a data layer, a strategy layer and a trading engine, with the explicit claim that data and strategies are expressed as intermediate representations so that multiple data interfaces and multiple trading interfaces can be plugged in, and so users can define their own strategies and factor mining. The second highlight covers machine learning, reinforcement learning and deep learning strategies plus an automated factor mining workflow. Read together, the architecture is a hub-and-spoke pattern: qlib supplies the modelling paradigms (the README mentions supervised learning, market dynamics modelling and RL), backtrader supplies the event loop for historical simulation, and vnpy supplies the live connection. Qbot's own code is the adapter between them. The payoff is that instrument coverage is broad by construction: the README lists stocks, funds, futures and cryptocurrency as supported trading objects. The cost is that every adapter is a place where semantics can drift. A factor computed on qlib's calendar and a signal consumed by a vnpy strategy do not share a type system, and the repository does not present a schema that would catch a mismatch.

Getting it running: clone shallow, install requirements, export PYTHONPATH

The README gives a short install sequence and points to docs/Install_guide.md for detail. The commands are: clone with depth 1 into your home directory, change into the Qbot folder, run pip install -r dev/requirements.txt, then export PYTHONPATH=${PYTHONPATH}:$(pwd):$(pwd)/backend/multi-fact/mfm_learner before python main.py. On macOS the README says to use pythonw main.py instead. Two things stand out in that sequence. First, the PYTHONPATH export reaches into backend/multi-fact/mfm_learner, which tells you the multi-factor learner is not installed as a package and must be importable from the source tree; anyone moving the folder or wrapping Qbot in a virtualenv-aware runner has to reproduce that path. Second, the interpreter constraint is stated bluntly: Qbot has only been tested on Python 3.8 and 3.9, and other versions are untested. The README also carries a maintenance instruction that runs against habit: it advises against forking, on the grounds that the project keeps updating and a fork will not see those updates, and suggests starring instead. For a platform whose value is in its adapters, that is a real operational constraint rather than a courtesy note.

The pinned-interpreter problem and the moving main branch

Two limitations compound each other. The first is the interpreter range. A platform that reaches into qlib, backtrader and vnpy inherits the version constraints of all three, and the README resolves the conflict by declaring 3.8 and 3.9 the tested set. If your environment is already on a newer Python, you are outside what the maintainers describe as tested, and the failure will most likely surface during dependency resolution or at import time rather than in a friendly error. The second is release cadence against branch cadence. The most recent tagged release in the material is qbot-pro_v1.2.1, published 2024-06-16 and marked as an alpha; before that, v1.0.1 in October 2023 and v1.0.0 in September 2023. The default branch, meanwhile, shows a last push of 2026-03-11. That gap means the documented install path and the branch you clone may not correspond to any tagged artefact, and the README's own advice not to fork removes the usual mitigation of pinning a known-good snapshot. A third, quieter risk: the README's headline describes the repository as updating, and the description field carries the same marker, so the surface you install today is not a frozen contract.

What the CI badges do and do not tell you

The repository runs CodeQL analysis, an AutoTrade workflow, Pylint and a coverage job, all visible as badges. Those are useful signals that the tree is linted and that some automated trading path is exercised in CI, and the coverage badge indicates the maintainers measure test reach. They are not evidence that the qlib-to-vnpy path works on your machine, because that path depends on your broker interface, your data source and your interpreter. The README leans on interactive documentation instead: an online docs site, a DeepWiki link for asking questions about the codebase, and a separate qbot-mini repository referenced in the project description. If you are evaluating Qbot for a real account, the DeepWiki and docs are where you should look for the live-trading contract, because the README excerpt stops short of specifying which brokers are wired up and under what authentication model. That is a gap worth naming rather than glossing: automated order routing is the part of this stack where an undocumented assumption costs money.

Where Qbot fits against a single-engine stack

The obvious alternative is to build on one engine and skip the integration layer. Backtrader alone, for instance, gives you a mature event-driven backtester with a broker abstraction and live feeds, and it is the component Qbot itself uses for the BackTest leg. Choosing backtrader directly means one set of semantics, one release cadence and one community, and you write your own data adapters. What you give up is the qlib side: the model zoo, the factor expression tooling and the reinforcement learning workflows that Qbot pulls in for its AI strategy claims, plus the GUI and quantstats dashboard. A second alternative is to stay inside qlib for research and never connect to a broker, which removes the vnpy dependency entirely but leaves you with no automated execution. Qbot's bet is that the integration is worth more than the sum of its parts for a solo operator. That bet is reasonable if you value a single tree and a GUI, and unreasonable if you value a dependency set you can reason about from a lockfile.

Licence, upgrade cost and what to verify before committing

Qbot is MIT-licensed, which is permissive and places few obligations on how you use or redistribute the code. That covers the repository itself; it does not cover the third-party engines and data sources Qbot wires together, and qlib, backtrader and vnpy each carry their own terms. Nothing here is legal advice, and if you plan to redistribute a modified Qbot or run it commercially, the licence of each upstream component is the thing to read, not just the MIT header on this repository. On upgrade cost: because the maintainer discourages forking and the default branch moves ahead of the tags, an upgrade is effectively a re-pull of the tree plus a re-run of pip install -r dev/requirements.txt and a re-check of the PYTHONPATH export. Budget for the possibility that a dependency bump breaks the qlib or vnpy adapter, since the tested interpreter window is narrow. The practical verification list is short and specific: confirm main.py starts under Python 3.8 or 3.9, confirm dev/requirements.txt resolves on your platform, and confirm from the docs and DeepWiki which brokers the live leg actually supports before you point it at an account.

Editorial conclusion

Qbot suits a Python-literate retail quant who wants one local tree containing qlib, backtrader and vnpy wiring, and who is willing to pin Python 3.8 or 3.9 and set PYTHONPATH by hand. It is the wrong tool if you need a supported, versioned dependency contract: the maintainer advises against forking because the project keeps moving, and the last tagged release is qbot-pro_v1.2.1 from June 2024. Before adopting, verify that main.py starts under your interpreter, that the requirements file resolves on your OS, and that the GUIs you actually intend to use are present on the default branch rather than only in the docs.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. UFund-Me/Qbot on GitHub