=======================
安装 scikit-learn
=======================

有多种方式可以安装 scikit-learn：

* :ref:`安装最新官方版本 <install_official_release>` 。这是大多数用户最好的选择。它将提供一个稳定的版本，并且大多数平台都有预构建的包。

* 安装由你的 :ref:`操作系统或 Python 发行版提供的 scikit-learn 版本 <install_by_distribution>` 。对于那些使用分发 scikit-learn 的操作系统或 Python 发行版的用户来说，这是一个快速选项。它可能不会提供最新的发布版本。

* :ref:`从源代码构建包 <install_bleeding_edge>` 。这对于想要最新功能并且不怕运行全新代码的用户来说是最佳选择。这也适用于希望为项目做出贡献的用户。

.. _install_official_release:

安装最新官方版本
=============================

.. `scss/install.scss` 覆盖了 sphinx-design 标签的一些默认样式

.. div:: install-instructions

  .. tab-set::
    :class: tabs-os

    .. tab-item:: Windows
      :class-label: tab-4

      .. tab-set::
        :class: tabs-package-manager

        .. tab-item:: pip
          :class-label: tab-6
          :sync: package-manager-pip

          安装 64 位的 Python 3 版本，例如从 `官方网站 <https://www.python.org/downloads/windows/>`__ 下载。

          现在创建一个 `虚拟环境 (venv) <https://docs.python.org/3/tutorial/venv.html>`_    并安装 scikit-learn。注意，虚拟环境是可选的，但强烈推荐，以避免与其他包发生潜在冲突。

          .. prompt:: powershell

            python -m venv sklearn-env
            sklearn-env\Scripts\activate  # 激活
            pip install -U scikit-learn

          为了检查你的安装，你可以使用：

          .. prompt:: powershell

            python -m pip show scikit-learn  # 显示 scikit-learn 版本和位置
            python -m pip freeze             # 显示环境中所有已安装的包
            python -c "import sklearn; sklearn.show_versions()"

        .. tab-item:: conda
          :class-label: tab-6
          :sync: package-manager-conda

          .. include:: ./install_instructions_conda.rst

    .. tab-item:: MacOS
      :class-label: tab-4

      .. tab-set::
        :class: tabs-package-manager

        .. tab-item:: pip
          :class-label: tab-6
          :sync: package-manager-pip

          使用 `homebrew <https://brew.sh/>`_    安装 Python 3（ `brew install python` ）
          或者从 `官方网站 <https://www.python.org/downloads/macos/>`__ 手动安装包。

          现在创建一个 `虚拟环境 (venv) <https://docs.python.org/3/tutorial/venv.html>`_    并安装 scikit-learn。
          请注意，虚拟环境是可选的，但强烈推荐，以避免与其他包发生潜在冲突。

          .. prompt:: bash

            python -m venv sklearn-env
            source sklearn-env/bin/activate  # 激活
            pip install -U scikit-learn

          为了检查您的安装，您可以使用：

          .. prompt:: bash

            python -m pip show scikit-learn  # 显示 scikit-learn 版本和位置
            python -m pip freeze             # 显示环境中所有已安装的包
            python -c "import sklearn; sklearn.show_versions()"

        .. tab-item:: conda
          :class-label: tab-6
          :sync: package-manager-conda

          .. include:: ./install_instructions_conda.rst

    .. tab-item:: Linux
      :class-label: tab-4

      .. tab-set::
        :class: tabs-package-manager

        .. tab-item:: pip
          :class-label: tab-6
          :sync: package-manager-pip

          Python 3 通常在大多数 Linux 发行版上默认安装。要检查您是否已安装，请尝试：

          .. prompt:: bash

            python3 --version
            pip3 --version

          如果您没有安装 Python 3，请从您的发行版包管理器安装 `python3` 和 `python3-pip` 。

          现在创建一个 `虚拟环境 (venv) <https://docs.python.org/3/tutorial/venv.html>`_    并安装 scikit-learn。
          请注意，虚拟环境是可选的，但强烈推荐，以避免与其他包发生潜在冲突。

          .. prompt:: bash

            python3 -m venv sklearn-env
            source sklearn-env/bin/activate  # 激活
            pip3 install -U scikit-learn

          为了检查您的安装，您可以使用：

          .. prompt:: bash

            python3 -m pip show scikit-learn  # 显示 scikit-learn 版本和位置
            python3 -m pip freeze             # 显示环境中所有已安装的包
            python3 -c "import sklearn; sklearn.show_versions()"

        .. tab-item:: conda
          :class-label: tab-6
          :sync: package-manager-conda

          .. include:: ./install_instructions_conda.rst

使用独立的虚拟环境如 pip venv 或 conda 可以安装特定版本的 scikit-learn 及其依赖，而不受已安装的 Python 包的影响。特别是在 Linux 上，不建议将 pip 包与发行版包管理器（apt、dnf、pacman...）管理的包一起安装。

请注意，您应该始终记得在每次启动新的终端会话时激活您选择的环境，然后再运行任何 Python 命令。

如果您还没有安装 NumPy 或 SciPy，您也可以使用 conda 或 pip 安装这些包。使用 pip 时，请确保使用 *二进制轮子*，并且 NumPy 和 SciPy 不会从源代码重新编译，这可能会在特定操作系统和硬件配置（如 Raspberry Pi 上的 Linux）下发生。

Scikit-learn 的绘图功能（即以 `plot\_` 开头和以 `Display` 结尾的函数和类）需要 Matplotlib。一些示例需要 Matplotlib、scikit-image、pandas 或 seaborn。scikit-learn 依赖的最小版本及其用途如下所列。

.. include:: min_dependency_table.rst

.. warning::

    Scikit-learn 0.20 是支持 Python 2.7 和 Python 3.4 的最后一个版本。
    Scikit-learn 0.21 支持 Python 3.5-3.7。
    Scikit-learn 0.22 支持 Python 3.5-3.8。
    Scikit-learn 0.23-0.24 需要 Python 3.6 或更高版本。
    Scikit-learn 1.0 支持 Python 3.7-3.10。
    Scikit-learn 1.1、1.2 和 1.3 支持 Python 3.8-3.12。
    Scikit-learn 1.4 需要 Python 3.9 或更高版本。

.. _install_by_distribution:

第三方分发的 scikit-learn
=========================

一些第三方分发版提供了与它们的包管理系统集成的 scikit-learn 版本。

这些分发版可以简化用户的安装和升级过程，因为集成包括了自动安装 scikit-learn 所需的依赖项（numpy、scipy）的能力。

以下是提供自己的 scikit-learn 版本的 OS 和 Python 分发版的不完全列表。

Alpine Linux
------------

Alpine Linux 的包通过 `官方仓库 <https://pkgs.alpinelinux.org/packages?name=py3-scikit-learn>`__ 提供，名为 ``py3-scikit-learn`` 用于 Python。可以通过输入以下命令来安装：

.. prompt:: bash

  sudo apk add py3-scikit-learn


Arch Linux
----------

Arch Linux 的包通过 `官方仓库 <https://www.archlinux.org/packages/?q=scikit-learn>`_    提供，名为 ``python-scikit-learn`` 用于 Python。可以通过输入以下命令来安装：

.. prompt:: bash

  sudo pacman -S python-scikit-learn


Debian/Ubuntu
-------------

Debian/Ubuntu 的包分为三个不同的包，分别名为 ``python3-sklearn`` （Python 模块）、 ``python3-sklearn-lib`` （低级实现和绑定）、 ``python3-sklearn-doc`` （文档）。注意，scikit-learn 需要 Python 3，因此需要使用带有 `python3-` 前缀的包名。可以使用 ``apt-get`` 安装这些包：

.. prompt:: bash

  sudo apt-get install python3-sklearn python3-sklearn-lib python3-sklearn-doc


Fedora
------

Fedora 的包名为 ``python3-scikit-learn`` ，适用于 Python 3 版本，这是 Fedora 中唯一可用的版本。可以使用 ``dnf`` 安装：

.. prompt:: bash

  sudo dnf install python3-scikit-learn


NetBSD
------
scikit-learn 可以通过 `pkgsrc-wip <http://pkgsrc-wip.sourceforge.net/>`_    获取：
https://pkgsrc.se/math/py-scikit-learn


MacPorts for Mac OSX
--------------------

MacPorts 包的名称是 ``py<XY>-scikits-learn`` ，其中 ``XY`` 表示 Python 版本。可以通过输入以下命令来安装：

.. prompt:: bash

  sudo port install py39-scikit-learn


Anaconda 和 Enthought Deployment Manager 适用于所有支持的平台
---------------------------------------------------------------------

 `Anaconda <https://www.anaconda.com/download>`_    和
 `Enthought Deployment Manager <https://assets.enthought.com/downloads/>`_   
都提供了 scikit-learn，以及大量适用于 Windows、Mac OSX 和 Linux 的科学 Python 库。

Anaconda 在其免费发行版中提供了 scikit-learn。


Intel Extension for Scikit-learn
--------------------------------

Intel 维护了一个针对 x86_64 架构优化的包，可通过 `pip` 在 PyPI 中获取，以及在 `main` 、 `conda-forge` 和 `intel` conda 渠道中获取：

.. prompt:: bash

  conda install scikit-learn-intelex

这个包包含了许多估计器的 Intel 优化版本。每当没有替代实现时，scikit-learn 实现将作为后备。这些优化的求解器来自 oneDAL C++ 库，针对 x86_64 架构进行了优化，并且针对多核 Intel CPU 进行了优化。

请注意，这些求解器默认情况下未启用，请参阅 `scikit-learn-intelex <https://intel.github.io/scikit-learn-intelex/latest/what-is-patching.html>`_    文档以获取更多使用场景的详细信息。直接导出示例：

.. prompt:: python >>>

  from sklearnex.neighbors import NearestNeighbors

通过自动化持续集成运行完整的 scikit-learn 测试套件来检查与标准 scikit-learn 求解器的兼容性，报告在 https://github.com/intel/scikit-learn-intelex。如果您在使用 `scikit-learn-intelex` 时遇到任何问题，请在他们的 `issue tracker <https://github.com/intel/scikit-learn-intelex/issues>`__ 上报告问题。


WinPython for Windows
---------------------

 `WinPython <https://winpython.github.io/>`_    项目将 scikit-learn 作为附加插件分发。


故障排除
========

如果在安装 scikit-learn 时遇到意外失败，您可以将问题提交到 `issue tracker <https://github.com/scikit-learn/scikit-learn/issues>`_  。在此之前，请确保检查以下常见问题。

.. _windows_longpath:

Windows 上文件路径长度限制导致的错误
-------------------------------------------------

如果 Python 安装在嵌套位置（例如用户主目录下的 `AppData` 文件夹结构），当达到 Windows 的默认路径大小限制时，pip 可能无法安装包，例如：

    C:\Users\username>C:\Users\username\AppData\Local\Microsoft\WindowsApps\python.exe -m pip install scikit-learn
    Collecting scikit-learn
    ...
    Installing collected packages: scikit-learn
    ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory: 'C:\\Users\\username\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.7_qbz5n2kfra8p0\\LocalCache\\local-packages\\Python37\\site-packages\\sklearn\\datasets\\tests\\data\\openml\\292\\api-v1-json-data-list-data_name-australian-limit-2-data_version-1-status-deactivated.json.gz'
在这种情况下，可以通过使用 ``regedit`` 工具在 Windows 注册表中解除该限制：

#. 在 Windows 开始菜单中输入 "regedit" 以启动 ``regedit`` 。

#. 转到 ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem`` 键。

#. 编辑该键的 ``LongPathsEnabled`` 属性的值并将其设置为 1。

#. 重新安装 scikit-learn（忽略之前的损坏安装）：

   .. prompt:: powershell

      pip install --exists-action=i scikit-learn