Environment:Recommenders team Recommenders Python Core Dependencies

Knowledge Sources	Recommenders setup.py SETUP.md
Domains	Infrastructure, Recommendation_Systems
Last Updated	2026-02-10 00:00 GMT

Overview

Python 3.8-3.11 environment with NumPy < 2.0, Pandas 2.x, scikit-learn, and 15+ core dependencies for recommendation system development.

Description

This environment defines the base Python runtime and core package dependencies required by all Recommenders workflows. It provides the data manipulation (Pandas, NumPy), machine learning (scikit-learn, LightGBM), NLP (NLTK, Transformers), and utility libraries that underpin every recommender algorithm in the repository. The environment is officially tested on Linux only, though community usage on Windows and macOS exists with caveats.

Usage

Use this environment for any Recommenders workflow. Every SAR, NCF, ALS, NRMS, and Benchmarking pipeline requires these core dependencies. GPU, Spark, and Experimental extras build on top of this base.

System Requirements

Category	Requirement	Notes
OS	Linux (POSIX)	Only officially supported platform (classifiers declare `Operating System :: POSIX :: Linux`)
Python	>= 3.8, <= 3.11	`python_requires=">=3.6"` in setup.py but classifiers declare 3.8-3.11
Build Tools	setuptools >= 52, wheel >= 0.36	Defined in `pyproject.toml`
Disk	~2 GB	For package installation plus downloaded datasets

Dependencies

Core Python Packages

• `category-encoders` >= 2.6.0, < 3
• `cornac` >= 2.3.0, < 3 (Python >= 3.9) or >= 1.15.2, <= 2.2.2 (Python <= 3.8)
• `hyperopt` >= 0.2.7, < 1
• `lightgbm` >= 4.0.0, < 5
• `locust` >= 2.12.2, < 3
• `memory-profiler` >= 0.61.0, < 1
• `nltk` >= 3.8.1, < 4
• `notebook` >= 6.5.5, < 8
• `numba` >= 0.57.0, < 1
• `numpy` < 2.0.0 (pinned due to issue #2224)
• `pandas` > 2.0.0, < 3.0.0
• `pandera[strategies]` >= 0.15.0 (Python >= 3.9) or >= 0.6.5, < 0.18 (Python <= 3.8)
• `retrying` >= 1.3.4, < 2
• `scikit-learn` >= 1.2.0, < 2
• `seaborn` >= 0.13.0, < 1
• `statsmodels` >= 0.14.4 (Python >= 3.9) or <= 0.14.1 (Python <= 3.8)
• `transformers` >= 4.27.0, < 5

Build System

• `numpy` >= 1.15, < 2 (build-time requirement in `pyproject.toml`)
• `setuptools` >= 52
• `wheel` >= 0.36

Credentials

No credentials are required for the core environment. Individual workflows may require dataset download URLs that are publicly accessible.

Quick Install

# Install core package
pip install recommenders

# Install with all extras (GPU + Spark + Dev)
pip install "recommenders[all]"

# On zsh, quote the extras bracket
pip install 'recommenders[gpu,spark]'

Code Evidence

NumPy version pin from `setup.py:40`:

"numpy<2.0.0",  # See https://github.com/recommenders-team/recommenders/issues/2224

Python-version-conditional dependencies from `setup.py:31-32`:

"cornac>=1.15.2,<=2.2.2;python_version<='3.8'",
"cornac>=2.3.0,<3;python_version>='3.9'",

Build system requirements from `pyproject.toml:1-6`:

[build-system]
requires = [
    "setuptools>=52",
    "wheel>=0.36",
    "numpy>=1.15,<2",
]

Platform declaration from `setup.py:118`:

"Operating System :: POSIX :: Linux",

Common Errors

Error Message	Cause	Solution
`numpy` version conflict errors	NumPy 2.0+ installed, breaking compatibility	Pin `numpy<2.0.0` per issue #2224
`scikit-surprise` import failure	Removed from core deps due to NumPy 2.0 issue	Install via `pip install "recommenders[experimental]"` or wait for #2224 fix
`zsh: no matches found: recommenders[gpu]`	zsh interprets brackets as glob patterns	Quote the argument: `pip install 'recommenders[gpu]'`

Compatibility Notes

• Linux: Primary supported platform. All CI tests run on Linux.
• Windows: Not officially declared in classifiers. Spark workflows require additional environment variables (`JAVA_HOME`, `SPARK_HOME`, `HADOOP_HOME`).
• macOS: May require Homebrew installation of LightGBM before pip install. Apple Silicon (M1/M2) GPU support is not yet documented.
• Python 3.8: Several packages have different version constraints (cornac, pandera, statsmodels, numpy for GPU). Being phased out.
• Python 3.12+: Not yet declared in classifiers. SARplus sub-project explicitly excludes it (`python_requires=">=3.6,<3.12"`).

Related Pages

• Implementation:Recommenders_team_Recommenders_Load_Pandas_Df
• Implementation:Recommenders_team_Recommenders_Python_Stratified_Split
• Implementation:Recommenders_team_Recommenders_Python_Chrono_Split
• Implementation:Recommenders_team_Recommenders_SARSingleNode_Init
• Implementation:Recommenders_team_Recommenders_SARSingleNode_Fit
• Implementation:Recommenders_team_Recommenders_SARSingleNode_Recommend_K_Items
• Implementation:Recommenders_team_Recommenders_Python_Evaluation_Metrics
• Implementation:Recommenders_team_Recommenders_NCF_Dataset_Init
• Implementation:Recommenders_team_Recommenders_NCF_Init_And_Fit
• Implementation:Recommenders_team_Recommenders_NCF_Predict
• Implementation:Recommenders_team_Recommenders_Benchmark_Prepare_Training
• Implementation:Recommenders_team_Recommenders_Benchmark_Train_Models
• Implementation:Recommenders_team_Recommenders_Benchmark_Predict_And_Recommend
• Implementation:Recommenders_team_Recommenders_Benchmark_Metric_Functions
• Implementation:Recommenders_team_Recommenders_Benchmark_Results_Analysis
• Implementation:Recommenders_team_Recommenders_Start_Or_Get_Spark
• Implementation:Recommenders_team_Recommenders_Load_Spark_Df
• Implementation:Recommenders_team_Recommenders_Spark_Random_Split
• Implementation:Recommenders_team_Recommenders_PySpark_ALS
• Implementation:Recommenders_team_Recommenders_ALSModel_Transform
• Implementation:Recommenders_team_Recommenders_Spark_Evaluation_Classes
• Implementation:Recommenders_team_Recommenders_Get_Mind_Data_Set
• Implementation:Recommenders_team_Recommenders_Prepare_Hparams
• Implementation:Recommenders_team_Recommenders_NRMSModel_Init
• Implementation:Recommenders_team_Recommenders_BaseModel_Run_Eval
• Implementation:Recommenders_team_Recommenders_BaseModel_Fit
• Implementation:Recommenders_team_Recommenders_BaseModel_Run_Fast_Eval