diff --git a/doc/install.rst b/doc/install.rst index ce7fa80647fe3..20cd565f40622 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -1,33 +1,22 @@ -.. _installation-instructions: +.. _install_scikit_learn: -======================= Installing scikit-learn ======================= -There are different ways to install scikit-learn: - -* :ref:`Install the latest official release `. This - is the best approach for most users. It will provide a stable version - and pre-built packages are available for most platforms. - -* Install the version of scikit-learn provided by your - :ref:`operating system or Python distribution `. - This is a quick option for those who have operating systems or Python - distributions that distribute scikit-learn. - It might not provide the latest release version. - -* :ref:`Building the package from source - `. This is best for users who want the - latest-and-greatest features and aren't afraid of running - brand-new code. This is also needed for users who wish to contribute to the - project. +Scikit-learn can be installed from PyPI (using pip) or from conda-forge (using +conda). Both methods are fully supported and widely used. If you already use +conda, conda-forge provides optimized packages for scientific computing. If you +prefer pip, PyPI wheels are equally valid. - -.. _install_official_release: +We recommend installing scikit-learn in an isolated environment to avoid +conflicts with other packages. Below are basic instructions for common operating +systems. Installing the latest release ============================= +To install scikit-learn, follow the instructions for your operating system: + .. raw:: html @@ -60,76 +41,51 @@ Installing the latest release .. tab-item:: pip :class-label: tab-6 - :sync: package-manager-pip - Install the 64-bit version of Python 3, for instance from the - `official website `__. + 1. Download and install the 64-bit Python 3 from the + `Windows official website `_. - Now create a `virtual environment (venv) - `_ and install scikit-learn. - Note that the virtual environment is optional but strongly recommended, in - order to avoid potential conflicts with other packages. + 2. Create a virtual environment (recommended): - .. prompt:: powershell + .. prompt:: powershell - python -m venv sklearn-env - sklearn-env\Scripts\activate # activate - pip install -U scikit-learn + python -m venv sklearn-env + sklearn-env\Scripts\activate - In order to check your installation, you can use: + 3. Install scikit-learn using pip: - .. prompt:: powershell + .. prompt:: powershell - python -m pip show scikit-learn # show scikit-learn version and location - python -m pip freeze # show all installed packages in the environment - python -c "import sklearn; sklearn.show_versions()" + pip install -U scikit-learn - .. tab-item:: conda - :class-label: tab-6 - :sync: package-manager-conda + 4. Verify the installation: - .. include:: ./install_instructions_conda.rst + .. prompt:: powershell - .. tab-item:: MacOS - :class-label: tab-4 + python -m pip show scikit-learn + python -c "import sklearn; sklearn.show_versions()" - .. tab-set:: - :class: tabs-package-manager - - .. tab-item:: pip + .. tab-item:: conda :class-label: tab-6 - :sync: package-manager-pip - - Install Python 3 using `homebrew `_ (`brew install python`) - or by manually installing the package from the `official website - `__. - Now create a `virtual environment (venv) - `_ and install scikit-learn. - Note that the virtual environment is optional but strongly recommended, in - order to avoid potential conflicts with other packges. + 1. Install Conda using the + `Miniforge installers `_. - .. prompt:: bash + 2. Create a new Conda environment and install scikit-learn: - python -m venv sklearn-env - source sklearn-env/bin/activate # activate - pip install -U scikit-learn + .. prompt:: powershell - In order to check your installation, you can use: + conda create -n sklearn-env -c conda-forge scikit-learn + conda activate sklearn-env - .. prompt:: bash + 3. Verify the installation: - python -m pip show scikit-learn # show scikit-learn version and location - python -m pip freeze # show all installed packages in the environment - python -c "import sklearn; sklearn.show_versions()" - - .. tab-item:: conda - :class-label: tab-6 - :sync: package-manager-conda + .. prompt:: powershell - .. include:: ./install_instructions_conda.rst + conda list scikit-learn + python -c "import sklearn; sklearn.show_versions()" - .. tab-item:: Linux + .. tab-item:: macOS :class-label: tab-4 .. tab-set:: @@ -137,213 +93,152 @@ Installing the latest release .. tab-item:: pip :class-label: tab-6 - :sync: package-manager-pip - Python 3 is usually installed by default on most Linux distributions. To - check if you have it installed, try: + 1. Install Python 3 using `Homebrew `_ or from the + `macOS official website `_. - .. prompt:: bash + 2. Create a virtual environment (recommended): - python3 --version - pip3 --version + .. prompt:: bash - If you don't have Python 3 installed, please install `python3` and - `python3-pip` from your distribution's package manager. + python3 -m venv sklearn-env + source sklearn-env/bin/activate - Now create a `virtual environment (venv) - `_ and install scikit-learn. - Note that the virtual environment is optional but strongly recommended, in - order to avoid potential conflicts with other packages. + 3. Install scikit-learn using pip: - .. prompt:: bash + .. prompt:: bash - python3 -m venv sklearn-env - source sklearn-env/bin/activate # activate - pip3 install -U scikit-learn + pip install -U scikit-learn - In order to check your installation, you can use: + 4. Verify the installation: - .. prompt:: bash + .. prompt:: bash - python3 -m pip show scikit-learn # show scikit-learn version and location - python3 -m pip freeze # show all installed packages in the environment - python3 -c "import sklearn; sklearn.show_versions()" + python3 -m pip show scikit-learn + python3 -c "import sklearn; sklearn.show_versions()" .. tab-item:: conda :class-label: tab-6 - :sync: package-manager-conda - - .. include:: ./install_instructions_conda.rst - - -Using an isolated environment such as pip venv or conda makes it possible to -install a specific version of scikit-learn with pip or conda and its dependencies -independently of any previously installed Python packages. In particular under Linux -it is discouraged to install pip packages alongside the packages managed by the -package manager of the distribution (apt, dnf, pacman...). -Note that you should always remember to activate the environment of your choice -prior to running any Python command whenever you start a new terminal session. + 1. Install Conda using the + `Miniforge installers `_. -If you have not installed NumPy or SciPy yet, you can also install these using -conda or pip. When using pip, please ensure that *binary wheels* are used, -and NumPy and SciPy are not recompiled from source, which can happen when using -particular configurations of operating system and hardware (such as Linux on -a Raspberry Pi). + 2. Create a new Conda environment and install scikit-learn: -Scikit-learn plotting capabilities (i.e., functions starting with `plot\_` -and classes ending with `Display`) require Matplotlib. The examples require -Matplotlib and some examples require scikit-image, pandas, or seaborn. The -minimum version of scikit-learn dependencies are listed below along with its -purpose. + .. prompt:: bash -.. include:: min_dependency_table.rst + conda create -n sklearn-env -c conda-forge scikit-learn + conda activate sklearn-env -.. warning:: + 3. Verify the installation: - Scikit-learn 0.20 was the last version to support Python 2.7 and Python 3.4. - Scikit-learn 0.21 supported Python 3.5-3.7. - Scikit-learn 0.22 supported Python 3.5-3.8. - Scikit-learn 0.23-0.24 required Python 3.6 or newer. - Scikit-learn 1.0 supported Python 3.7-3.10. - Scikit-learn 1.1, 1.2 and 1.3 support Python 3.8-3.12 - Scikit-learn 1.4 requires Python 3.9 or newer. - -.. _install_by_distribution: - -Third party distributions of scikit-learn -========================================= + .. prompt:: bash -Some third-party distributions provide versions of -scikit-learn integrated with their package-management systems. - -These can make installation and upgrading much easier for users since -the integration includes the ability to automatically install -dependencies (numpy, scipy) that scikit-learn requires. - -The following is an incomplete list of OS and python distributions -that provide their own version of scikit-learn. - -Alpine Linux ------------- - -Alpine Linux's package is provided through the `official repositories -`__ as -``py3-scikit-learn`` for Python. -It can be installed by typing the following command: - -.. prompt:: bash - - sudo apk add py3-scikit-learn - - -Arch Linux ----------- - -Arch Linux's package is provided through the `official repositories -`_ as -``python-scikit-learn`` for Python. -It can be installed by typing the following command: - -.. prompt:: bash - - sudo pacman -S python-scikit-learn - - -Debian/Ubuntu -------------- - -The Debian/Ubuntu package is split in three different packages called -``python3-sklearn`` (python modules), ``python3-sklearn-lib`` (low-level -implementations and bindings), ``python-sklearn-doc`` (documentation). -Note that scikit-learn requires Python 3, hence the need to use the `python3-` -suffixed package names. -Packages can be installed using ``apt-get``: - -.. prompt:: bash - - sudo apt-get install python3-sklearn python3-sklearn-lib python-sklearn-doc + conda list scikit-learn + python3 -c "import sklearn; sklearn.show_versions()" + .. tab-item:: Linux + :class-label: tab-4 -Fedora ------- + .. tab-set:: + :class: tabs-package-manager -The Fedora package is called ``python3-scikit-learn`` for the python 3 version, -the only one available in Fedora. -It can be installed using ``dnf``: + .. tab-item:: pip + :class-label: tab-6 -.. prompt:: bash + 1. Ensure Python 3 and pip are installed: - sudo dnf install python3-scikit-learn + .. prompt:: bash + python3 --version + pip3 --version -NetBSD ------- + 2. Create a virtual environment (recommended): -scikit-learn is available via `pkgsrc-wip `_: -https://pkgsrc.se/math/py-scikit-learn + .. prompt:: bash + python3 -m venv sklearn-env + source sklearn-env/bin/activate -MacPorts for Mac OSX --------------------- + 3. Install scikit-learn using pip: -The MacPorts package is named ``py-scikits-learn``, -where ``XY`` denotes the Python version. -It can be installed by typing the following -command: + .. prompt:: bash -.. prompt:: bash + pip3 install -U scikit-learn - sudo port install py39-scikit-learn + 4. Verify the installation: + .. prompt:: bash -Anaconda and Enthought Deployment Manager for all supported platforms ---------------------------------------------------------------------- + python3 -m pip show scikit-learn + python3 -c "import sklearn; sklearn.show_versions()" -`Anaconda `_ and -`Enthought Deployment Manager `_ -both ship with scikit-learn in addition to a large set of scientific -python library for Windows, Mac OSX and Linux. + .. tab-item:: conda + :class-label: tab-6 -Anaconda offers scikit-learn as part of its free distribution. + 1. Install Conda using the + `Miniforge installers `_. + 2. Create a new Conda environment and install scikit-learn: -Intel Extension for Scikit-learn --------------------------------- + .. prompt:: bash -Intel maintains an optimized x86_64 package, available in PyPI (via `pip`), -and in the `main`, `conda-forge` and `intel` conda channels: + conda create -n sklearn-env -c conda-forge scikit-learn + conda activate sklearn-env -.. prompt:: bash + 3. Verify the installation: - conda install scikit-learn-intelex + .. prompt:: bash -This package has an Intel optimized version of many estimators. Whenever -an alternative implementation doesn't exist, scikit-learn implementation -is used as a fallback. Those optimized solvers come from the oneDAL -C++ library and are optimized for the x86_64 architecture, and are -optimized for multi-core Intel CPUs. + conda list scikit-learn + python3 -c "import sklearn; sklearn.show_versions()" -Note that those solvers are not enabled by default, please refer to the -`scikit-learn-intelex `_ -documentation for more details on usage scenarios. Direct export example: +--- -.. prompt:: python >>> +**Important**: Using an isolated environment such as ``pip venv`` or ``conda`` +ensures that scikit-learn and its dependencies are installed independently of +other Python packages. Always activate the environment before running Python +commands to avoid conflicts. - from sklearnex.neighbors import NearestNeighbors +For more details on Python packaging and virtual environments, refer to the +`PyPackaging Native documentation `_. -Compatibility with the standard scikit-learn solvers is checked by running the -full scikit-learn test suite via automated continuous integration as reported -on https://github.com/intel/scikit-learn-intelex. If you observe any issue -with `scikit-learn-intelex`, please report the issue on their -`issue tracker `__. +Third-party distributions of scikit-learn +========================================= -WinPython for Windows ---------------------- +Several third-party distributions include scikit-learn in their package +managers. This can simplify installation and upgrading scikit-learn, as +dependencies (NumPy, SciPy, etc.) are often handled automatically. Below is an +incomplete list: + +- **Alpine Linux** (`py3-scikit-learn docs + `_): + ``sudo apk add py3-scikit-learn`` +- **Arch Linux** (`python-scikit-learn + `_): + ``sudo pacman -S python-scikit-learn`` +- **Debian/Ubuntu** (`python3-sklearn + `_): + ``sudo apt-get install python3-sklearn python3-sklearn-lib python-sklearn-doc`` +- **Fedora** (`python3-scikit-learn + `_): + ``sudo dnf install python3-scikit-learn`` +- **NetBSD**: via `pkgsrc-wip `_ +- **macOS (MacPorts)** (`py-scikits-learn + `_): + ``sudo port install py39-scikit-learn`` +- **Intel Extension for scikit-learn** (`docs + `_): install via + ``pip install scikit-learn-intelex`` or + ``conda install scikit-learn-intelex`` +- **WinPython for Windows** (`homepage + `_) + +.. note:: + Third-party repositories may not always provide the latest release. Consult + each distributor’s documentation for more details. -The `WinPython `_ project distributes -scikit-learn as an additional plugin. Troubleshooting @@ -351,37 +246,27 @@ Troubleshooting If you encounter unexpected failures when installing scikit-learn, you may submit an issue to the `issue tracker `_. -Before that, please also make sure to check the following common issues. - -.. _windows_longpath: +Before that, please check these common issues: Error caused by file path length limit on Windows ------------------------------------------------- -It can happen that pip fails to install packages when reaching the default path -size limit of Windows if Python is installed in a nested location such as the -`AppData` folder structure under the user home directory, for instance:: - - 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' - -In this case it is possible to lift that limit in the Windows registry by -using the ``regedit`` tool: +Pip can fail to install packages when hitting the default path-size limit on +Windows, especially if Python is installed under ``AppData``. For example:: -#. Type "regedit" in the Windows start menu to launch ``regedit``. + C:\Users\username>... + ERROR: Could not install packages due to an OSError: [Errno 2] No such file + or directory: + 'C:\\Users\\username\\AppData\\Local\\...\\sklearn\\datasets\\tests\\data\\...' -#. Go to the - ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem`` - key. +To fix this, enable long paths via the Windows registry: -#. Edit the value of the ``LongPathsEnabled`` property of that key and set - it to 1. +1. Type ``regedit`` in the Start menu. +2. Go to ``Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem``. +3. Edit the ``LongPathsEnabled`` property to ``1``. -#. Reinstall scikit-learn (ignoring the previous broken installation): +Then reinstall scikit-learn (ignoring the prior broken install): - .. prompt:: powershell +.. prompt:: powershell - pip install --exists-action=i scikit-learn + pip install --exists-action=i scikit-learn