Python recommendation tools

LensKit is a set of Python tools for experimenting with and studying recommender systems. It provides support for training, running, and evaluating recommender algorithms in a flexible fashion suitable for research and education.

LensKit for Python (LKPY) is the successor to the Java-based LensKit project.

Important

If you use LensKit for Python in published research, please cite:

Michael D. Ekstrand. 2020. LensKit for Python: Next-Generation Software for Recommender Systems Experiments. In Proceedings of the 29th ACM International Conference on Information and Knowledge Management (CIKM '20). DOI:10.1145/3340531.3412778. arXiv:1809.03125 [cs.IR].

Note

LensKit had significant changes in the 2025.1 release. See the Migration Guide for details.

Installing

To install the current release with Anaconda (recommended):

conda install -c conda-forge lenskit

If you use Pixi, you can add it to your project:

pixi add lenskit

Or you can use pip (or uv):

pip install lenskit

To use the latest development version, install directly from GitHub:

pip install -U git+https://github.com/lenskit/lkpy

Then see Getting Started

Developing

To contribute to LensKit, clone or fork the repository, get to work, and submit a pull request. We welcome contributions from anyone; if you are looking for a place to get started, see the issue tracker.

Our development workflow is documented in the wiki; the wiki also contains other information on developing LensKit. User-facing documentation is at https://lkpy.lenskit.org.

We use uv for developing LensKit and managing development environments. Our pyproject.toml file contains the Python development dependencies; you also need a working Rust compiler (typically via rustup). Before setting up to work on LensKit, you therefore need:

• Git
• uv
• rustup and a working Rust compiler (rustup install stable)
• A working C compiler compatible with Python
  • On Windows, this is either Visual Studio (with C++ development) or the Visual C++ Build Tools. See the Rustup Windows install instructions for details.
  • On Mac, install Xcode.
  • On Linux, see your system package manager instructions.

Windows

On Windows, you can install dependencies (except for the Visual C++ tools) with winget:

> winget install Git.Git astral-sh.uv Rustlang.Rustup
> rustup install stable-msvc

Mac

On Mac, you can install the dependencies with Homebrew:

$ brew install git uv rustup

Once you have the dependencies installed, set up your LensKit development environment:

$ uv venv -p 3.12
$ uv sync

If you want all extras (may not work on Windows), do:

$ uv sync --all-extras

You can then activate the virtual environment to have the tools available and run tools like pytest:

$ . ./.venv/bin/activate

Testing Changes

You should always test your changes by running the LensKit test suite:

pytest tests

If you want to use your changes in a LensKit experiment, you can locally install your modified LensKit into your experiment's environment. We recommend using separate environments for LensKit development and for each experiment; you will need to install the modified LensKit into your experiment's repository:

uv pip install -e /path/to/lkpy

Resources

• Documentation
• Discussion and Announcements

Acknowledgements

This material is based upon work supported by the National Science Foundation under Grant No. IIS 17-51278. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.