scikit-surprise安装失败求助：subprocess报错与packages配置缺失问题

开发者阿泽

2026-7-2

scikit-surprise 安装失败问题排查与解决

我尝试用命令python -m pip install --no-use-pep517 scikit-surprise安装scikit-surprise，一直碰到以下错误：

error: subprocess-exited-with-error

× python setup.py bdist_wheel did not run successfully.
│ exit code: 1
╰─> [129 lines of output]

********************************************************************************
        Requirements should be satisfied by a PEP 517 installer.
        If you are using pip, you can try `pip install --use-pep517`.
        ********************************************************************************

Package 'surprise.prediction_algorithms' is absent from the packages configuration.
!!

********************************************************************************
        ############################
        # Package would be ignored #
        ############################
        Python recognizes 'surprise.prediction_algorithms' as an importable package[^1],
        but it is absent from setuptools' `packages` configuration.

        This leads to an ambiguous overall configuration. If you want to distribute this
        package, please make sure that 'surprise.prediction_algorithms' is explicitly added
        to the `packages` configuration field.

        Alternatively, you can also rely on setuptools' discovery methods
        (for example by using `find_namespace_packages(...)`/`find_namespace:`
        instead of `find_packages(...)`/`find:`).

        You can read more about "package discovery" on setuptools documentation page:

        - https://setuptools.pypa.io/en/latest/userguide/package_discovery.html

        If you don't want 'surprise.prediction_algorithms' to be distributed and are
        already explicitly excluding 'surprise.prediction_algorithms' via
        `find_namespace_packages(...)/find_namespace` or `find_packages(...)/find`,
        you can try to use `exclude_package_data`, or `include-package-data=False` in
        combination with a more fine grained `package-data` configuration.

        You can read more about "package data files" on setuptools documentation page:

        - https://setuptools.pypa.io/en/latest/userguide/datafiles.html


        [^1]: For Python, any directory (with suitable naming) can be imported,
              even if it does not contain any `.py` files.
              On the other hand, currently there is no concept of package data
              directory, all directories are treated like packages.
        ********************************************************************************

note: This error originates from a subprocess, and is likely not a problem with pip.
ERROR: Failed building wheel for scikit-surprise
Running setup.py clean for scikit-surprise
Failed to build scikit-surprise
ERROR: Could not build wheels for scikit-surprise, which is required to install pyproject.toml-based projects

我已经试过这些操作，但都没解决：

把Python 3.10升级到最新的Python 3.12
更新pip、VSCode、setuptools、wheel
确认已安装Microsoft Visual C++ 14.0或更高版本
按照错误提示里的建议操作
尝试用conda安装，也没成功

错误原因

核心问题是官方scikit-surprise包与新版setuptools不兼容：

官方包的setup.py未正确声明surprise.prediction_algorithms子包，新版setuptools对包发现规则更严格，会将未声明的目录判定为无效包，导致wheel构建失败。
你使用的--no-use-pep517参数强制启用旧版安装流程，反而放大了兼容性冲突——虽然错误提示建议用PEP517安装，但官方包本身的配置缺陷仍会导致失败。

解决办法

方法1：安装社区维护的兼容版本

官方scikit-surprise长期未更新，社区有适配新版Python和setuptools的分支，直接安装该版本：

# 带加速版本
pip install scikit-surprise[accelerated] -f https://github.com/NicolasHug/surprise/releases
# 基础版本
pip install git+https://github.com/NicolasHug/surprise.git

方法2：降级setuptools到兼容版本

若坚持使用官方包，先降级setuptools再安装：

pip install setuptools==65.5.0
python -m pip install scikit-surprise

方法3：手动修改配置后构建

克隆项目仓库：

git clone https://github.com/NicolasHug/surprise.git
cd surprise

打开setup.py，找到packages参数，修改为：

packages=['surprise', 'surprise.prediction_algorithms'],

执行本地安装：

pip install .

内容的提问来源于stack exchange，提问作者yana