recommenders: Microsoft's Python Library for Building Recommendation Systems

What recommenders Solves and Who Uses It

recommenders addresses the bootstrapping problem in recommendation system development: starting from scratch with a new algorithm requires implementing the model, wiring up the data pipeline, writing evaluation metrics, and managing hyperparameter search, all before you can compare it meaningfully against a baseline. This library packages all of that work into runnable Jupyter notebooks organized by algorithm, so a researcher or developer can reach a working result on a standard dataset in minutes rather than days.

The project is maintained under the Linux Foundation of AI and Data, having originated at Microsoft. According to the README, the target audience is researchers, developers, and enthusiasts who want to prototype, experiment with, or bring to production a range of recommendation algorithms. The library is not a narrow implementation of one method; it covers the full spectrum from matrix factorization on sparse data to deep learning models that require GPU resources.

The structure reflects this breadth. Five task areas organize the repository: preparing and loading data, building models, evaluating algorithms, tuning and optimizing hyperparameters, and operationalizing models on Azure. Each area has a corresponding examples subdirectory with notebooks.

Repository Layout and How to Navigate It

The repository is organized so that the examples directory is the main entry point for most users. It contains subdirectories for each of the five task areas, numbered 00 through 05, plus benchmarks and tutorial folders. The 00_quick_start subdirectory holds one-notebook introductions to each algorithm. The 02_model_collaborative_filtering and 02_model_content_based_filtering directories contain deeper-dive notebooks that walk through the math and implementation of specific algorithms.

The recommenders package in the source tree contains the Python utilities that support the notebooks: data loaders formatted for each algorithm, evaluation metric implementations, and dataset split utilities. These can be imported directly from Python code outside the notebook context if you want to use them in your own pipeline.

The scenarios directory covers practical applications of recommendation systems in real-world settings. The wiki page linked from the README contains additional documents and presentations for teams who want more context on algorithm choices and architecture decisions.

Installing recommenders and Running a First Notebook

The README recommends uv for environment management and describes it as 10 to 100 times faster than conda or pip. The Getting Started section provides complete steps for Linux and WSL:

curl -LsSf https://astral.sh/uv/install.sh | sh

After installing uv, create a virtual environment targeting Python 3.11:

uv venv ~/.venvs/recommenders --python 3.11
source ~/.venvs/recommenders/bin/activate

Install the core recommenders package:

uv pip install recommenders

The core package runs all CPU-only notebooks. To run notebooks in Jupyter, install the ipykernel package:

uv pip install ipykernel

Then register the environment as a Jupyter kernel using the ipykernel install command documented in the Getting Started section of the README. After that, open any notebook in the examples directory and select the recommenders kernel. The quick-start notebook for ALS on MovieLens at examples/00_quick_start/als_movielens.ipynb is a reasonable first notebook, as ALS has no GPU requirement and the MovieLens dataset is small enough to run on a laptop.

Algorithms and What They Require

The README lists the available algorithms in a table with their type, a short description, and a link to the corresponding quick-start or deep-dive notebook. Collaborative filtering algorithms include Alternating Least Squares (ALS) for matrix factorization on explicit or implicit feedback in Spark, Bayesian Personalized Ranking (BPR) via Cornac for implicit feedback ranking, and Bilateral Variational Autoencoder (BiVAE) for generative modeling of user-item interactions.

Deep learning algorithms include xDeepFM (eXtreme Deep Factorization Machine) for implicit and explicit feedback with user and item features, and DKN (Deep Knowledge-Aware Network) which incorporates a knowledge graph for news or article recommendation. Sequential models like Caser and A2SVD capture user preference patterns over time.

The extras system separates the dependency sets:

- `[gpu]` enables GPU-accelerated models - `[spark]` enables Spark models including ALS - `[dev]` adds development tools - `[all]` combines gpu, spark, and dev - `[experimental]` adds models that are not thoroughly tested or require extra installation steps

Teams who do not need Spark or GPU support should install the core package only; the full [all] install pulls in a heavier dependency set including GPU and Spark libraries.

Evaluation and Hyperparameter Tuning

The repository treats evaluation as a first-class concern. The examples/03_evaluate directory contains notebooks covering offline metrics such as precision at K, recall at K, normalized discounted cumulative gain, and mean average precision. These utilities are implemented in the recommenders package itself, so you can import them outside the notebook context to plug into your own evaluation loop.

The examples/04_model_select_and_optimize directory covers hyperparameter search. The library includes hyperopt as a dependency for Bayesian hyperparameter optimization across algorithm configurations. This matters because recommendation algorithms are sensitive to hyperparameters: the learning rate, number of latent factors, and regularization strength in a matrix factorization model have a large effect on the resulting ranking quality, and exhaustive grid search becomes impractical as the parameter space grows.

The README does not document an opinionated recommendation for which evaluation metric to use as a primary signal; that choice depends on the business objective. The benchmark notebooks in examples/06_benchmarks compare algorithms on standard datasets, which provides a reference point for calibrating expectations before tuning.

Limitations and Dependency Weight

recommenders is not a lightweight library. The core install_requires list in setup.py includes category-encoders, cornac, hyperopt, lightgbm, locust, memory-profiler, nltk, notebook, numpy, pandas, protobuf, pyarrow, retrying, scikit-learn, seaborn, statsmodels, and transformers. That is a substantial set of packages with their own transitive dependencies. Teams building a minimal production inference service should not use recommenders as a deployment library; it is a research and development resource. The notebook examples are where the project's value lies, not in a thin model serving layer.

The GPU extras add TensorFlow and related packages, which carry their own version compatibility constraints. The README notes that protobuf is capped below version 5 for TensorFlow compatibility, referencing a specific issue in the repository. Teams using Python environments with existing deep learning frameworks may encounter version conflicts.

ALS runs in PySpark, which means it requires a Spark installation. Teams without a Spark setup cannot use the ALS algorithm regardless of other configurations. The README recommends checking SETUP.md for setup instructions on platforms other than Linux and WSL.

Maintenance, License, and Production Path

The repository last received a push on 2026-09-25, and the latest release is version 1.2.1 from December 2024. The project is under the Linux Foundation AI and Data umbrella, which provides organizational continuity beyond a single maintainer. The MIT license imposes no restriction on commercial use.

The release notes for 1.2.1 describe bug fixes for dependency issues, security improvements, and a review of the notebooks and libraries. Version 1.2.0, released in May 2024, and the earlier 1.1.1 from July 2022 are also available, reflecting a slow but ongoing release cadence.

For teams that need to bring a recommendation model to production, the examples/05_operationalize directory contains notebooks for deploying models on Azure. This is the most direct production path that the repository documents, and it assumes an Azure environment. Teams targeting other infrastructure would need to adapt the patterns from those notebooks.

Editorial conclusion

recommenders suits researchers and developers who need a working starting point for collaborative filtering, content-based filtering, or deep learning recommendation models, with ready-to-run Jupyter notebooks for each algorithm. It is a poor fit for teams that want a lightweight inference library: the core install pulls in a large set of dependencies including lightgbm, transformers, and cornac, and the GPU and Spark extras add more. Teams targeting production deployment on Azure will find the most direct support in the operationalize examples. The MIT license imposes no restriction on commercial use. Verify that your Python version is 3.11 before starting, as the Getting Started guide uses that version explicitly in the uv venv command.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. recommenders-team/recommenders on GitHub
5. Releases