Surprise is a Python scikit building and analyzing recommender systems.

Surprise was designed with the following purposes in mind:

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

Getting started, example

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

from surprise import SVD
from surprise import Dataset
from surprise import evaluate, print_perf

# Load the movielens-100k dataset (download it if needed),
# and split it into 3 folds for cross-validation.
data = Dataset.load_builtin('ml-100k')

# We'll use the famous SVD algorithm.
algo = SVD()

# Evaluate performances of our algorithm on the dataset.
perf = evaluate(algo, data, measures=['RMSE', 'MAE'])



Evaluating RMSE, MAE of algorithm SVD.

        Fold 1  Fold 2  Fold 3  Mean
MAE     0.7475  0.7447  0.7425  0.7449
RMSE    0.9461  0.9436  0.9425  0.9441

Surprise can do much more (e.g, GridSearch)! 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-folds cross-validation procedure. The datasets are the Movielens 100k and 1M datasets. The folds are the same for all the algorithms (the random seed is set to 0). All experiments are run on a small laptop with Intel Core i3 1.7 GHz, 4Go RAM. The execution time is the real execution time, as returned by the GNU time command.

Movielens 100k RMSE MAE Time (s)
NormalPredictor 1.5228 1.2242 4
BaselineOnly .9445 .7488 5
KNNBasic .9789 .7732 27
KNNWithMeans .9514 .7500 30
KNNBaseline .9306 .7334 44
SVD .9364 .7381 46
SVD++ .9200 .7253 31min
NMF .9634 .7572 55
Slope One .9454 .7430 25
Co clustering .9678 .7579 15
Movielens 1M RMSE MAE Time (min)
NormalPredictor 1.5037 1.2051 < 1
BaselineOnly .9086 .7194 < 1
KNNBasic .9207 .7250 22
KNNWithMeans .9292 .7386 22
KNNBaseline .8949 .7063 44
SVD .8738 .6858 7
NMF .9155 .7232 9
Slope One .9065 .7144 8
Co clustering .9155 .7174 2


The easiest way is to use pip (you’ll need numpy):

$ pip install numpy
$ pip install scikit-surprise

If you use conda, you can install the package following these guidelines (still using pip).

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 https://github.com/NicolasHug/surprise.git
$ cd surprise
$ python setup.py 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{http://surpriselib.com}},
year = {2017}


The following persons have contributed to Surprise:

Charles-Emmanuel Dias, Lukas Galke, Pierre-François Gimenez, Nicolas Hug, Hengji Liu, Maher Malaeb, Naturale0, nju-luke, Skywhat, Mike Lee Williams, Chenchen Xu.

Thanks a lot :) !

Contributing, feedback, contact

Any kind of feedback/criticism would be greatly appreciated (software design, documentation, improvement ideas, spelling mistakes, etc…).

If you’d like to see some features or algorithms implemented in Surprise, please let us know!

Please feel free to contribute (see guidelines) and send pull requests!

For bugs, issues or questions about Surprise, you can use the GitHub project page (please don’t send me emails as there would be no record for future users).