Registry / ai-ml / scikit-surprise

scikit-surprise

library1.1.5pypypi✓ verified 85d ago

scikit-surprise (Surprise) is a Python scikit for building and analyzing recommender systems. Version 1.1.4 is the current release. It supports prediction-based and neighborhood-based collaborative filtering, matrix factorization, and evaluation metrics. Releases are infrequent (last stable was 1.1.1 in 2020, then 1.1.3/1.1.4 in 2025).

ai-ml

pip install scikit-surprise

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · SCIKIT-SURPRISE

scikit-surprise

ai-mlpythonv1.1.5

Install

7.3s avg

Import

780ms

Disk

237MB

Pass rate

4/ 10

Env Coverage4 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.1.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 7.3s

py 3.11

✕ build_error

✓ 7.2s

py 3.12

✕ build_error

✓ 7.5s

py 3.13

✕ build_error

✓ 7.4s

py 3.9

✕ build_error

237MB installed

● package 237MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Dataset

✓ from surprise import Dataset

Correct import path.

Reader

✓ from surprise import Reader

Used to parse ratings from file or dataframe.

SVD

✓ from surprise import SVD

Standard matrix factorization algorithm.

accuracy

✓ from surprise import accuracy

For RMSE, MAE, etc.

cross_validate

✓ from surprise.model_selection import cross_validate

✗ from surprise.model_selection import cross_validate

Common mistake: importing from surprise directly (no cross_validate at top level).

GridSearchCV

✓ from surprise.model_selection import GridSearchCV

✗ from surprise.model_selection import GridSearchCV

Same as above.

Loads the Movielens 100k dataset, trains SVD, and evaluates RMSE.

from surprise import Dataset, Reader, SVD, accuracy from surprise.model_selection import train_test_split # Load the built-in movielens dataset data = Dataset.load_builtin('ml-100k') trainset, testset = train_test_split(data, test_size=0.25) algo = SVD() algo.fit(trainset) predictions = algo.test(testset) rmse = accuracy.rmse(predictions) print(f"RMSE: {rmse}")

Debug

Known issues

gotchaDataset.load_builtin() downloads data to ~/.surprise_data by default. If the disk is full or permission denied, it raises an error. Ensure sufficient space or set SURPRISE_DATA_FOLDER environment variable.

fix

Set env var SURPRISE_DATA_FOLDER to a writable directory.

affects: all

breakingIn version 1.1.0+, the default similarity measure in KNNBasic changed from 'msd' to 'cosine'. If you rely on old behavior, specify 'msd' explicitly.

fix

sim_options = {'name': 'msd', 'user_based': True}

affects: >=1.1.0

gotchaWhen using custom datasets with Reader, the rating_scale must match the actual ratings. Mismatch leads to inaccurate predictions or errors.

fix

Always set rating_scale=(min_rating, max_rating) in Reader.

affects: all

deprecatedThe surprise.dump module is deprecated and may be removed in future versions. Use pickle or joblib directly on algorithm objects.

fix

import joblib; joblib.dump(algo, 'model.pkl')

affects: >=1.1.4

gotchaSVD and other algorithms require the dataset to have user and item IDs as integers or strings. If IDs are not consecutive integers, the algorithm still works but may be less efficient.

fix

Use Dataset.load_from_df() with DataFrame columns: user, item, rating.

affects: all

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'surprise'

Package not installed or installed under 'scikit-surprise' but imported as 'surprise'.

fix

pip install scikit-surprise. The import is 'import surprise' or 'from surprise import ...'.

ValueError: `rating_scale` must be a tuple (low, high).

Reader not initialized with rating_scale when using custom dataset.

fix

reader = Reader(rating_scale=(1, 5))

AttributeError: module 'surprise' has no attribute 'cross_validate'

cross_validate is in surprise.model_selection, not top-level surprise.

fix

from surprise.model_selection import cross_validate

FileNotFoundError: [Errno 2] No such file or directory: '~/.surprise_data/ml-100k/...'

Built-in dataset not downloaded (network issue or missing folder).

fix

Run Dataset.load_builtin('ml-100k') with internet; or set SURPRISE_DATA_FOLDER to an existing directory.

Upgrade

Version history

1.1.5latest on PyPI · released May 30, 2026

Audit

Dependencies

numpyrequiredRequired for numerical operations

scipyrequiredRequired for sparse matrix operations

joblibrequiredUsed for parallel execution

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/NicolasHug/Surprise ↗

packagehttps://pypi.org/project/scikit-surprise/ ↗

homepagehttps://surpriselib.com ↗