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].
Warning
This is the main branch of LensKit, following new development in preparation
for the 2024 release. It will be changing frequently and incompatibly. You
probably want to use a stable release.
To install the current release with Anaconda (recommended):
conda install -c conda-forge lenskit
Or you can use pip:
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
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 recommend using an Anaconda environment for developing LensKit. We provide a tool to automate setting up Conda environments from the LensKit dependencies; to create a dev environment, checkout LensKit, then run:
pipx --spec . lk-conda -n lkpy pyproject.toml dev-requirements.txt
conda activate lkpy
That will create and activate an environment named lkpy with all the LensKit
dependencies. You will also need to install the LensKit packages you want to
work on in editable mode to do things like run the tests:
pip install --no-deps -e lenskit
Each LensKit subpackage you want to work on will also need to be installed.
You can also use a standard virtual environment and vanilla Python to develop LensKit. To do this, the easiest way is to use uv:
uv venv -p python3.11
uv pip install -r full-dev-requirements.txt
You can also use traditional Pip:
python -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements-full-dev.txt
You should always test your changes by running the LensKit test suite:
python -m pytest
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:
conda activate my-exp
conda install -c conda-forge
cd /path/to/lkpy
pip install -e . --no-deps
You may need to first uninstall LensKit from your experiment repo; make sure that LensKit's dependencies are all still installed.
Once you have pushed your code to a GitHub branch, you can use a Git repository as
a Pip dependency in an environment.yml for your experiment, to keep using the
correct modified version of LensKit until your changes make it in to a release.
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.
