Skip to main content

An easy-to-use library for recommender systems.

Project description

GitHub version Documentation Status Build Status python versions License



Surprise is a Python scikit for building and analyzing recommender systems that deal with explicit rating data.

Surprise was designed with the following purposes in mind:

The name SurPRISE (roughly :) ) stands for Simple Python RecommendatIon System Engine.

Please note that surprise does not support implicit ratings or content-based information.

Getting started, example

Here is a simple example showing how you can (down)load a dataset, split it for 5-fold cross-validation, and compute the MAE and RMSE of the SVD algorithm.

from surprise import SVD
from surprise import Dataset
from surprise.model_selection import cross_validate

# Load the movielens-100k dataset (download it if needed).
data = Dataset.load_builtin('ml-100k')

# Use the famous SVD algorithm.
algo = SVD()

# Run 5-fold cross-validation and print results.
cross_validate(algo, data, measures=['RMSE', 'MAE'], cv=5, verbose=True)


Evaluating RMSE, MAE of algorithm SVD on 5 split(s).

            Fold 1  Fold 2  Fold 3  Fold 4  Fold 5  Mean    Std
RMSE        0.9311  0.9370  0.9320  0.9317  0.9391  0.9342  0.0032
MAE         0.7350  0.7375  0.7341  0.7342  0.7375  0.7357  0.0015
Fit time    6.53    7.11    7.23    7.15    3.99    6.40    1.23
Test time   0.26    0.26    0.25    0.15    0.13    0.21    0.06

Surprise can do much more (e.g, GridSearchCV)! You'll find more usage examples in the documentation .


Here are the average RMSE, MAE and total execution time of various algorithms (with their default parameters) on a 5-fold cross-validation procedure. The datasets are the Movielens 100k and 1M datasets. The folds are the same for all the algorithms. All experiments are run on a notebook with Intel Core i5 7th gen (2.5 GHz) and 8Go RAM. The code for generating these tables can be found in the benchmark example.

Movielens 100k RMSE MAE Time
SVD 0.934 0.737 0:00:11
SVD++ 0.92 0.722 0:09:03
NMF 0.963 0.758 0:00:15
Slope One 0.946 0.743 0:00:08
k-NN 0.98 0.774 0:00:10
Centered k-NN 0.951 0.749 0:00:10
k-NN Baseline 0.931 0.733 0:00:12
Co-Clustering 0.963 0.753 0:00:03
Baseline 0.944 0.748 0:00:01
Random 1.514 1.215 0:00:01
Movielens 1M RMSE MAE Time
SVD 0.873 0.686 0:02:13
SVD++ 0.862 0.673 2:54:19
NMF 0.916 0.724 0:02:31
Slope One 0.907 0.715 0:02:31
k-NN 0.923 0.727 0:05:27
Centered k-NN 0.929 0.738 0:05:43
k-NN Baseline 0.895 0.706 0:05:55
Co-Clustering 0.915 0.717 0:00:31
Baseline 0.909 0.719 0:00:19
Random 1.504 1.206 0:00:19


With pip (you'll need numpy, and a C compiler. Windows users might prefer using conda):

$ pip install numpy
$ pip install scikit-surprise

With conda:

$ conda install -c conda-forge scikit-surprise

For the latest version, you can also clone the repo and build the source (you'll first need Cython and numpy):

$ pip install numpy cython
$ git clone
$ cd surprise
$ python install


This project is licensed under the BSD 3-Clause license, so it can be used for pretty much everything, including commercial applications. Please let us know how Surprise is useful to you!

Here is a Bibtex entry if you ever need to cite Surprise in a research paper (please keep us posted, we would love to know if Surprise was helpful to you):

author =   {Hug, Nicolas},
title =    { {S}urprise, a {P}ython library for recommender systems},
howpublished = {\url{}},
year = {2017}


The following persons have contributed to Surprise:

ashtou, bobbyinfj, caoyi, Олег Демиденко, Charles-Emmanuel Dias, dmamylin, Lauriane Ducasse, Marc Feger, franckjay, Lukas Galke, Tim Gates, Pierre-François Gimenez, Zachary Glassman, Jeff Hale, Nicolas Hug, Janniks, jyesawtellrickson, Doruk Kilitcioglu, Ravi Raju Krishna, Hengji Liu, Maher Malaeb, Manoj K, James McNeilis, Naturale0, nju-luke, Jay Qi, Lucas Rebscher, Skywhat, David Stevens, TrWestdoor, Victor Wang, Mike Lee Williams, Jay Wong, Chenchen Xu, YaoZh1918.

Thanks a lot :) !

Development Status

Starting from version 1.1.0 (September 19), we will only maintain the package and provide bugfixes. No new features will be considered.

For bugs, issues or questions about Surprise, please use the GitHub project page. Please don't send emails (we will not answer).

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scikit-surprise-1.1.1.tar.gz (11.8 MB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page