Open research

mlfinlab on the PyPI index: packaging financial research code, and what happened next

Open research · Published 2026-10-30

For a quantitative researcher, publishing code on the Python Package Index (PyPI) turns a folder of scripts into something anyone can install with one command. mlfinlab, a library implementing techniques from Advances in Financial Machine Learning, is a well-known example: it was distributed on PyPI from 2019 and later moved from an open-source licence to a commercial one. This article explains how packaging works, why it matters for reproducible research, and what that licence change teaches about depending on other people's code.

What PyPI is

PyPI is the public repository of Python software, run by the Python Software Foundation. When a user types pip install followed by a package name, pip looks the name up on PyPI, downloads the matching distribution files and installs them along with their dependencies. Anyone can publish a package after creating an account, which is what makes the ecosystem so large and also why users should check what they install.

A package is published as one or more distributions: a source distribution (sdist) containing the code and build instructions, and usually one or more wheels, pre-built archives that install quickly. Metadata, including the version, dependencies, supported Python versions and licence, is declared in a pyproject.toml file according to standards maintained by the Python Packaging Authority.

Why packaging matters for research

• Reproducibility. A research result should be tied to a specific version of the code. Pinning package==1.4.2 in a requirements or lock file means someone else can recreate the same environment months later.
• Testing. Packaging encourages a test suite. For financial methods, good tests reproduce known results, for example the examples in a textbook, and check edge cases such as missing prices and overlapping events.
• Versioning. Semantic versioning (major.minor.patch) signals whether an update may break existing code. A change in how a function computes a label is a breaking change for anyone whose backtest depends on it.
• Documentation. A published package usually comes with documentation that explains parameters and assumptions, which is where many subtle errors in financial code hide.

The mlfinlab story

When Advances in Financial Machine Learning appeared in 2018, its code snippets were scattered through the text. mlfinlab, developed by Hudson & Thames, set out to collect and implement them as a tested library covering data structures such as dollar bars, triple-barrier labelling, fractional differentiation, sample weights, cross-validation and portfolio methods. It was published on PyPI, initially under an open-source licence, and grew quickly in popularity among students and researchers working through the book.

The project later changed course: newer versions were distributed under a commercial licence, requiring a paid subscription, and the openly licensed code stopped being developed. Older open-source releases had already been downloaded and forked by users, and several community projects have since reimplemented the same techniques under open licences.

The details of the licence terms belong to the project and have changed over time; anyone using the library should read the current licence on its official site or package page rather than rely on a summary.

Lessons about dependencies

The mlfinlab episode is a useful case study, regardless of one's view of the decision. Open-source maintainers are entitled to change the licence of future releases; what they cannot generally do is revoke the licence on code already released under an open licence. For a researcher, the practical lessons are:

1. Pin versions and keep a local copy of the exact distribution files your work depends on.
2. Read licences before building on a library, especially for commercial use. Permissive licences (MIT, BSD) and copyleft licences (GPL) impose different obligations.
3. Understand the method, not just the call. If a dependency disappears or changes, being able to reimplement the core function from the original paper protects the work.
4. Prefer active, well-tested projects, and check the number of maintainers. Single-maintainer projects are fragile.
5. Check package names carefully. PyPI has seen malicious packages with names similar to popular ones (typosquatting). Install from the official project name and, where possible, verify it from the project's own documentation.

Publishing your own research code

For readers who want to publish their own tools, the Python Packaging User Guide gives an up-to-date tutorial. The core steps are: organise the code as a package with a pyproject.toml; choose a build backend; build the sdist and wheel; test the upload on TestPyPI; then publish to PyPI, ideally using the "trusted publishing" mechanism, which lets a continuous-integration workflow upload releases without long-lived passwords or tokens. Choosing and stating a licence at the outset avoids the ambiguity that causes problems later.

For a broader view of the libraries available for quantitative finance, see getting started with open source for quantitative finance, and for the book's techniques themselves, our map of Advances in Financial Machine Learning.

Checking a package before you depend on it

A few minutes of checks before installing a research library can save trouble later. Look at the project's repository: how recently it was updated, how many maintainers it has, whether issues receive responses, and whether there is a test suite with continuous integration. Read the licence file and any additional terms on the project's website. Check the release history on PyPI to see whether versions follow a consistent numbering scheme and whether old versions remain available. Finally, try the library on a small example from the original paper or book and confirm the numbers match. If they do not, find out why before building research on it.