Skip to content
Get packs

Guide · Open source

How to use recommenders: install, run notebooks and build models

Updated · written with AI from the project's own documentation and checked against our catalogue data

Recommenders is an open-source Python package and set of Jupyter notebooks for building recommendation systems, such as suggesting movies or articles to users. It is aimed at data scientists, developers and students who want working examples and utilities. After this guide you will be able to install the core package, run an example notebook, and know which stages of the workflow the project covers.

Recommendersrecommenders-team/recommenders · ★ 22k · MIT

Quick start

  1. 1Install gcc. On Linux or WSL, make sure gcc is available. The README gives sudo apt install gcc as an Ubuntu example.
  2. 2Install uv. Run the README's uv install script to get the uv tool.
  3. 3Create a virtual environment. Create a Python 3.11 environment with uv venv and activate it.
  4. 4Install the core package. Run uv pip install recommenders to get the core package, which covers all CPU notebooks.
  5. 5Register a Jupyter kernel. Install ipykernel and register a kernel named recommenders so notebooks can use this environment.
  6. 6Clone and run an example. Clone the repository and run examples/00_quick_start/sar_movielens.ipynb with the Python (recommenders) kernel.

What Recommenders is and who it is for

Recommenders is a project whose objective is to help researchers, developers and enthusiasts prototype, experiment with and bring to production a range of classic and state-of-the-art recommendation systems. It is maintained under the Linux Foundation of AI and Data.

It is a library plus examples, not a finished product. If you need a recommendation service with no coding, this is not the right fit.

  • Data scientists prototyping recommendation models
  • Developers who want working examples of common algorithms
  • Students learning how recommenders are built and evaluated
  • Engineers who need data-splitting and evaluation utilities for their own models

Install Recommenders on Linux or WSL with uv

The README recommends uv for environment management and VS Code for development. Install gcc first if it is missing (on Ubuntu, the README suggests installing it with apt). The examples use Python 3.11.

Install uv, create a virtual environment, activate it, then install the core package. The core package can run all the CPU notebooks.

  • Prerequisites: Python 3.11, uv or another virtual environment tool, and gcc on Linux/WSL
  • For Windows and macOS setup and GPU, Spark or experimental configurations, see the project's SETUP.md
curl -LsSf https://astral.sh/uv/install.sh | sh uv venv ~/.venvs/recommenders --python 3.11 source ~/.venvs/recommenders/bin/activate uv pip install recommenders

Run an example notebook with a Jupyter kernel

To run the examples, install ipykernel and register a kernel that points at your environment. Then clone the repository and open a notebook such as the ALS quick start in VS Code.

The README's quick start notebook is examples/00_quick_start/sar_movielens.ipynb, and the workflow is: open the notebook, select the kernel named Python (recommenders), and run it.

  • Open a notebook, for example examples/00_quick_start/sar_movielens.ipynb
  • Select the Jupyter kernel "Python (recommenders)"
  • Run the notebook cells
uv pip install ipykernel python -m ipykernel install --user --name recommenders --display-name "Python (recommenders)" git clone https://github.com/recommenders-team/recommenders.git

Choose the right algorithm and extras

The README's algorithm table lists the available methods, including Alternating Least Squares (ALS), Cornac/Bayesian Personalized Ranking (BPR), LightFM/Factorization Machine, and xDeepFM. Each row says which environment it runs in (CPU, GPU or PySpark) and links to a quick start or deep dive notebook.

Optional extras add support for specific environments. The core install is enough for CPU notebooks.

  • [gpu]: needed for running GPU models
  • [spark]: needed for running Spark models
  • [dev]: needed for development on the repo
  • [all]: [gpu] plus [spark] plus [dev]
  • [experimental]: models that are not thoroughly tested and/or may need extra installation steps

Work through the five core tasks

The repository's examples are organised around five tasks: preparing data, modelling, evaluating with offline metrics, tuning hyperparameters, and operationalizing models. The library also includes utilities for loading datasets, evaluating model outputs and splitting training and test data.

The README says operationalization examples describe running models in production on Azure, so plan for that if you deploy.

  • Prepare Data: examples/01_prepare_data
  • Model: examples/00_quick_start and examples/02_model_collaborative_filtering
  • Evaluate: examples/03_evaluate
  • Model Select and Optimize: examples/04_model_select_and_optimize
  • Operationalize: examples/05_operationalize (on Azure)

What people use it for

  • Prototyping a movie recommender with the quick start notebooks
  • Comparing classic collaborative filtering methods such as ALS and BPR on the same data
  • Learning offline evaluation by running the evaluate examples
  • Building content-based recommendations for articles with the DKN or LightGBM examples
  • Reusing data-splitting and evaluation utilities in your own model code

Frequently asked questions

Is Recommenders free to use?

Yes. The project is licensed under the MIT License, and the README includes that licence notice. Check the LICENSE file in the repository for the full terms.

What do I need to install Recommenders?

The README uses Python 3.11 and uv or another virtual environment tool. On Linux or WSL, install gcc as well. The core package is installed with uv pip install recommenders.

Does Recommenders run on Windows or macOS?

The README's install steps are for Linux and WSL. It points to the SETUP.md guide for other platforms, including Windows and macOS.

Can I deploy Recommenders to production?

The repository includes an operationalization section, but the README describes it as operationalizing models on Azure. If you need deployment outside Azure, check the project documentation before you commit.

How does Recommenders compare to Surprise, LightFM or Implicit?

Recommenders is a broad collection of algorithms, notebooks and evaluation utilities in one repository. Surprise, LightFM, Implicit and RecBole are comparable projects, but this source does not compare their features or performance, so test the ones you shortlist on your own data.

Why does my notebook not find the recommenders package?

Make sure the notebook uses the Python (recommenders) kernel you registered with ipykernel, not a different Python environment. The README's workflow depends on selecting that kernel before running the notebook.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Recommenders suits data scientists, developers and students who want working Python examples and evaluation utilities for classic and deep learning recommenders. It is a poor fit for anyone who needs a finished recommendation product without coding, teams not using Python, or those who need production deployment outside Azure.

Install options & downloads