.. _advanced-installation:

.. include:: ../min_dependency_substitutions.rst

==================================================
安装 scikit-learn 的开发版本
==================================================

本节介绍如何安装 scikit-learn 的 **主分支** 版本。可以通过安装 nightly build 或从源代码构建来实现。

.. _install_nightly_builds:

安装 nightly builds
=========================

scikit-learn 项目的持续集成服务器每晚构建、测试并上传适用于最新 Python 版本的 wheel 包。

安装 nightly build 是尝试以下内容的快速方法：

- 下一个版本中将包含的新功能（即最近合并到主分支的拉取请求中的功能）；

- 检查自上次发布以来是否已修复您遇到的错误。

您可以使用 `scientific-python-nightly-wheels` 索引从 `anaconda.org` 的 PyPI 注册表安装 scikit-learn 的 nightly build：

.. prompt:: bash $

  pip install --pre --extra-index https://pypi.anaconda.org/scientific-python-nightly-wheels/simple scikit-learn

请注意，可能需要先卸载 scikit-learn 才能安装 scikit-learn 的 nightly builds。

.. _install_bleeding_edge:

从源代码构建
====================

从源代码构建是进行贡献（错误修复、新功能、代码或文档改进）所必需的。

.. _git_repo:

1. 使用 `Git <https://git-scm.com/>`_    从 Github 上的 `scikit-learn 仓库 <https://github.com/scikit-learn/scikit-learn>`_    检出最新的源代码：

   .. prompt:: bash $

     git clone git://github.com/scikit-learn/scikit-learn.git  # 如果您的连接较慢，请添加 --depth 1
     cd scikit-learn

   如果您计划提交拉取请求，则应从您的 fork 克隆。

2. 安装较新版本的 Python（撰写时为 3.9 或更高版本）：
   使用 Miniforge3_ 的实例。Miniforge 提供了一个基于 conda 的 Python 及其最流行的科学库的发行版。

   如果你通过 conda 安装了 Python，我们建议创建一个专用的 `conda 环境`_   ，包含 scikit-learn 的所有构建依赖项（即 NumPy_、SciPy_、Cython_、meson-python_ 和 Ninja_）：

   .. prompt:: bash $

     conda create -n sklearn-env -c conda-forge python numpy scipy cython meson-python ninja

   这并不总是必要的，但在激活新创建的 conda 环境之前打开一个新的提示符会更安全。

   .. prompt:: bash $

     conda activate sklearn-env

#. **conda 的替代方案：** 你可以使用其他安装的 Python，只要它们足够新（在撰写本文时为 3.9 或更高版本）。以下是如何为 Linux 系统的 Python 创建构建环境的示例。构建依赖项通过 `pip` 安装在一个专用的 virtualenv_ 中，以避免干扰系统上安装的其他 Python 程序：

   .. prompt:: bash $

     python3 -m venv sklearn-env
     source sklearn-env/bin/activate
     pip install wheel numpy scipy cython meson-python ninja

#. 为你的平台安装一个支持 OpenMP_ 的编译器。查看适用于 :ref:`compiler_windows` 、:ref:`compiler_macos` 、:ref:`compiler_linux` 和 :ref:`compiler_freebsd` 的说明。

#. 使用 pip 构建项目：

   .. prompt:: bash $

     pip install --editable . \
        --verbose --no-build-isolation \
        --check-build-dependencies \
        --config-settings editable-verbose=true

#. 检查已安装的 scikit-learn 的版本号是否以 `.dev0` 结尾：

   .. prompt:: bash $

     python -c "import sklearn; sklearn.show_versions()"

#. 请参考 :ref:`developers_guide` 和 :ref:`pytest_tips` 来运行你选择的模块的测试。

.. note::

    `--config-settings editable-verbose=true` 是可选的，但推荐使用
    为了避免在导入 `sklearn` 时出现意外情况。 `meson-python` 通过在执行 `import sklearn` 时重新构建 `sklearn` 来实现可编辑安装。使用推荐的设置，当这种情况发生时，你会看到一条消息，而不是可能在没有反馈的情况下等待，并想知道为什么这么慢。额外的好处是，这意味着你只需要运行一次 `pip install` 命令， `sklearn` 会在导入 `sklearn` 时自动重新构建。

依赖项
-------

运行时依赖项
~~~~~~~~~~~~~

Scikit-learn 在构建时和运行时都需要以下依赖项：

- Python (>= 3.8),
- NumPy (>= |NumpyMinVersion|),
- SciPy (>= |ScipyMinVersion|),
- Joblib (>= |JoblibMinVersion|),
- threadpoolctl (>= |ThreadpoolctlMinVersion|).

构建依赖项
~~~~~~~~~~

构建 Scikit-learn 还需要：

..
    # 以下位置需要与 Cython 版本保持同步：
    # - .circleci 配置文件
    # - sklearn/_build_utils/__init__.py
    # - 高级安装指南

- Cython >= |CythonMinVersion|
- C/C++ 编译器和匹配的 OpenMP_ 运行时库。有关更多详细信息，请参阅 :ref:`平台系统特定说明
  <platform_specific_instructions>` 。

.. note::

   如果编译器不支持 OpenMP，构建将会在没有 OpenMP 功能的情况下完成。这不推荐，因为它会迫使某些估计器以顺序模式运行，而不是利用基于线程的并行性。设置 ``SKLEARN_FAIL_NO_OPENMP`` 环境变量（在 Cython 化之前）将强制构建失败，如果 OpenMP 不受支持。

自版本 0.21 以来，scikit-learn 自动检测并使用 SciPy 在运行时使用的线性代数库。因此，scikit-learn 没有对 OpenBlas、Atlas、Blis 或 MKL 等 BLAS/LAPACK 实现的构建依赖。

测试依赖项
~~~~~~~~~~

运行测试需要：

- pytest >= |PytestMinVersion|
一些测试还需要 `pandas <https://pandas.pydata.org>`_   .


从标签构建特定版本
------------------

如果你想构建一个稳定版本，你可以 ``git checkout <VERSION>`` 来获取该特定版本的代码，或者从 GitHub 下载该版本的 zip 归档文件。

.. _platform_specific_instructions:

特定平台的安装说明
====================

以下是针对每个支持的平台安装带有 OpenMP 支持的工作 C/C++ 编译器以构建 scikit-learn Cython 扩展的说明。

.. _compiler_windows:

Windows
-------

首先，下载 `Visual Studio 2019 构建工具安装程序
<https://aka.ms/vs/17/release/vs_buildtools.exe>`_   .

运行下载的 `vs_buildtools.exe` 文件，在安装过程中，你需要确保选择 "使用 C++ 的桌面开发"，类似于以下截图：

.. image:: ../images/visual-studio-build-tools-selection.png

其次，找出你运行的是 64 位还是 32 位 Python。构建命令取决于 Python 解释器的架构。你可以在 ``cmd`` 或 ``powershell`` 控制台中运行以下命令来检查架构：

.. prompt:: bash $

    python -c "import struct; print(struct.calcsize('P') * 8)"

对于 64 位 Python，通过在 ``cmd`` 或 Anaconda Prompt（如果你使用 Anaconda）中运行以下命令来配置构建环境：

.. sphinx-prompt 1.3.0（用于 doc-min-dependencies CI 任务）不支持 `batch` 提示类型，
.. 因此我们通过使用已知的提示类型和显式的提示文本来解决。
..
.. prompt:: bash C:\>

    SET DISTUTILS_USE_SDK=1
    "C:\Program Files (x86)\Microsoft Visual Studio\2019\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64

将 ``x64`` 替换为 ``x86`` 以构建 32 位 Python。

请注意，上述路径可能因用户而异。目的是指向将设置必要环境的 "vcvarsall.bat" 文件。
当前命令提示符中的环境变量。

最后，使用此命令提示符构建 scikit-learn：

.. prompt:: bash $

    pip install --editable . \
        --verbose --no-build-isolation \
        --config-settings editable-verbose=true

.. _compiler_macos:

macOS
-----

macOS 上的默认 C 编译器 Apple clang（令人困惑地别名为 `/usr/bin/gcc` ），并不直接支持 OpenMP。我们提供两种替代方案来启用 OpenMP 支持：

- 要么使用 conda 安装 `conda-forge::compilers` ；

- 或者使用 Homebrew 安装 `libomp` 来扩展默认的 Apple clang 编译器。

对于 Apple Silicon M1 硬件，截至撰写时（2021 年 1 月），仅知以下 conda-forge 方法有效。您可以使用 `miniforge 安装程序 <https://github.com/conda-forge/miniforge#miniforge>`_    安装 `macos/arm64` 版本的 conda。

来自 conda-forge 的 macOS 编译器
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

如果您使用 conda 包管理器（版本 >= 4.7），您可以从 conda-forge 频道安装 `compilers` 元包，该包提供了基于 llvm 工具链的启用 OpenMP 的 C/C++ 编译器。

首先安装 macOS 命令行工具：

.. prompt:: bash $

    xcode-select --install

建议使用专用的 `conda 环境`_    来从源代码构建 scikit-learn：

.. prompt:: bash $

    conda create -n sklearn-dev -c conda-forge python numpy scipy cython \
        joblib threadpoolctl pytest compilers llvm-openmp meson-python ninja

并非总是必要，但在激活新创建的 conda 环境之前打开一个新的提示符更为安全。

.. prompt:: bash $

    conda activate sklearn-dev
    make clean
    pip install --editable . \
        --verbose --no-build-isolation \
        --config-settings editable-verbose=true

.. note::

    如果您收到任何冲突的依赖错误消息，尝试注释掉 `~/.condarc` 文件中的任何自定义 conda 配置。
特别是 ``channel_priority: strict`` 指令已知会导致此设置出现问题。

您可以使用以下命令检查自定义编译器是否已从 conda forge 正确安装：

.. prompt:: bash $

    conda list

其中应包含 ``compilers`` 和 ``llvm-openmp`` 。

编译器元包将自动设置自定义环境变量：

.. prompt:: bash $

    echo $CC
    echo $CXX
    echo $CFLAGS
    echo $CXXFLAGS
    echo $LDFLAGS

它们指向您的 ``sklearn-dev`` conda 环境中的文件和文件夹（特别是在 bin/、include/ 和 lib/ 子文件夹中）。例如， ``-L/path/to/conda/envs/sklearn-dev/lib`` 应出现在 ``LDFLAGS`` 中。

在日志中，您应该看到使用 conda 安装的 clang 和 clang++ 编译器构建的编译扩展，并带有 ``-fopenmp`` 命令行标志。

macOS 来自 Homebrew 的编译器
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

另一个解决方案是为 macOS 上默认提供的 clang 编译器启用 OpenMP 支持。

首先安装 macOS 命令行工具：

.. prompt:: bash $

    xcode-select --install

安装适用于 macOS 的 Homebrew_ 包管理器。

安装 LLVM OpenMP 库：

.. prompt:: bash $

    brew install libomp

设置以下环境变量：

.. prompt:: bash $

    export CC=/usr/bin/clang
    export CXX=/usr/bin/clang++
    export CPPFLAGS="$CPPFLAGS -Xpreprocessor -fopenmp"
    export CFLAGS="$CFLAGS -I/usr/local/opt/libomp/include"
    export CXXFLAGS="$CXXFLAGS -I/usr/local/opt/libomp/include"
    export LDFLAGS="$LDFLAGS -Wl,-rpath,/usr/local/opt/libomp/lib -L/usr/local/opt/libomp/lib -lomp"

最后，以详细模式构建 scikit-learn（以检查编译器命令中是否存在 ``-fopenmp`` 标志）：

.. prompt:: bash $

    make clean
    pip install --editable . \
        --verbose --no-build-isolation \
        --config-settings editable-verbose=true

.. _compiler_linux:

Linux
-----
Linux 系统编译器
~~~~~~~~~~~~~~~~

从源代码安装 scikit-learn 而不使用 conda 需要你已经安装了 scikit-learn 的 Python 开发头文件和一个支持 OpenMP 的工作 C/C++ 编译器（通常是 GCC 工具链）。

为基于 Debian 的操作系统（例如 Ubuntu）安装构建依赖项：

.. prompt:: bash $

    sudo apt-get install build-essential python3-dev python3-pip

然后按常规进行：

.. prompt:: bash $

    pip3 install cython
    pip3 install --editable . \
        --verbose --no-build-isolation \
        --config-settings editable-verbose=true

Cython 和运行时依赖项（numpy、scipy 和 joblib）的预编译轮应自动安装在 ``$HOME/.local/lib/pythonX.Y/site-packages`` 中。或者，你可以在 virtualenv_ 或 `conda 环境`_    中运行上述命令，以完全隔离通过系统包管理器安装的 Python 包。在使用隔离环境时，上述命令中的 ``pip3`` 应替换为 ``pip`` 。

当运行时依赖项的预编译轮对于你的架构（例如 ARM）不可用时，你可以安装系统版本：

.. prompt:: bash $

    sudo apt-get install cython3 python3-numpy python3-scipy

在 Red Hat 及其克隆系统（例如 CentOS）上，使用以下命令安装依赖项：

.. prompt:: bash $

    sudo yum -y install gcc gcc-c++ python3-devel numpy scipy

conda-forge 的 Linux 编译器
~~~~~~~~~~~~~~~~~~~~~~~~~~

或者，使用 conda 在用户文件夹中安装最新版本的 GNU C 编译器工具链（GCC）：

.. prompt:: bash $

    conda create -n sklearn-dev -c conda-forge python numpy scipy cython \
        joblib threadpoolctl pytest compilers meson-python ninja

打开一个新的提示符再激活新创建的 conda 环境并不是总是必要的，但这样做更安全。

.. prompt:: bash $

    conda activate sklearn-dev
    pip install --editable . \
        --verbose --no-build-isolation \
        --config-settings editable-verbose=true

.. _compiler_freebsd:

FreeBSD
-------

FreeBSD 12.0 和 11.2 基础系统中包含的 clang 编译器不支持 OpenMP。您需要从软件包（或 ports）中安装 `openmp` 库：

.. prompt:: bash $

    sudo pkg install openmp

这将在 ``/usr/local/include`` 中安装头文件，并在 ``/usr/local/lib`` 中安装库。由于默认情况下不会搜索这些目录，您可以设置环境变量到这些位置：

.. prompt:: bash $

    export CFLAGS="$CFLAGS -I/usr/local/include"
    export CXXFLAGS="$CXXFLAGS -I/usr/local/include"
    export LDFLAGS="$LDFLAGS -Wl,-rpath,/usr/local/lib -L/usr/local/lib -lomp"

最后，使用标准命令构建包：

.. prompt:: bash $

    pip install --editable . \
        --verbose --no-build-isolation \
        --config-settings editable-verbose=true

对于即将发布的 FreeBSD 12.1 和 11.3 版本，OpenMP 将包含在基础系统中，这些步骤将不再必要。

.. _OpenMP: https://en.wikipedia.org/wiki/OpenMP
.. _Cython: https://cython.org
.. _meson-python: https://mesonbuild.com/meson-python
.. _Ninja: https://ninja-build.org/
.. _NumPy: https://numpy.org
.. _SciPy: https://www.scipy.org
.. _Homebrew: https://brew.sh
.. _virtualenv: https://docs.python.org/3/tutorial/venv.html
.. _conda environment: https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html
.. _Miniforge3: https://github.com/conda-forge/miniforge#miniforge3