.. _installing-scikit-image:

Installing scikit-image

First, you need to have the Python language installed. Two popular routes are the pip-based Python.org installers <https://www.python.org/downloads/>_ and the conda-based miniforge <https://github.com/conda-forge/miniforge>_.
Install scikit-image via pip <#install-via-pip>_ or conda <#install-via-conda>_, as appropriate.
Or, build the package from source <#installing-scikit-image-for-contributors>_. Do this if you'd like to contribute to development.

Supported platforms

Windows 64-bit on x86 processors
macOS on x86 and ARM (M1, etc.) processors
Linux 64-bit on x86 and ARM processors

While we do not officially support other platforms, you could still try building from source <#building-from-source>_.

Version check

To see whether scikit-image is already installed or to check if an install has worked, run the following in a Python shell or Jupyter notebook:

.. code-block:: python

import skimage as ski print(ski.version)

or, from the command line:

.. code-block:: sh

python -c "import skimage; print(skimage.version)"

(Try python3 if python is unsuccessful.)

You'll see the version number if scikit-image is installed and an error message otherwise.

Installation via pip and conda

.. _install-via-pip:

pip ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Prerequisites to a pip install: you must be able to use pip on your command line to install packages.

We strongly recommend the use of a virtual environment <https://towardsdatascience.com/virtual-environments-104c62d48c54?gi=2532aa12906#ee81>_. A virtual environment creates a clean Python environment that does not interfere with the existing system installation, can be easily removed, and contains only the package versions your application needs.

To install the current scikit-image you'll need at least Python 3.11. If your Python is older, pip will find the most recent compatible version.

.. code-block:: sh

Update pip

python -m pip install -U pip

Install scikit-image

python -m pip install -U scikit-image

Some additional dependencies are required to access all example datasets in skimage.data. Install them using:

.. code-block:: sh

python -m pip install -U scikit-image[data]

To install optional scientific Python packages that expand scikit-image's capabilities to include, e.g., parallel processing, use:

.. code-block:: sh

python -m pip install -U scikit-image[optional]

.. warning::

Do not use the command ``sudo`` and ``pip`` together as ``pip`` may
overwrite critical system libraries.

.. _install-via-conda:

conda ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We recommend miniforge <https://github.com/conda-forge/miniforge>, a minimal distribution that makes use of conda-forge <https://conda-forge.org>. It installs Python and provides virtual environments.

Once you have your conda environment set up, install scikit-image with:

.. code-block:: sh

conda install scikit-image

System package managers

Using a package manager (apt, dnf, etc.) to install scikit-image or other Python packages is not your best option, since you're likely to get an older version. It also becomes harder to install other Python packages not provided by the package manager.

Downloading all demo datasets

Some of our example images (in skimage.data) are hosted online and are not installed by default. These images are downloaded upon first access. If you prefer to download all demo datasets, so they can be accessed offline, ensure that pooch is installed, then run:

.. code-block:: sh

python -c 'import skimage as ski; ski.data.download_all()'

Additional help

If you still have questions, reach out through

our user forum <https://forum.image.sc/tags/scikit-image>_
our developer forum <https://discuss.scientific-python.org/c/contributor/skimage>_
our chat channel <https://skimage.zulipchat.com/>_

To suggest a change in these instructions, please open an issue on GitHub <https://github.com/scikit-image/scikit-image/issues/new>_.

Installing scikit-image for contributors

Your system needs a:

C compiler,
C++ compiler, and
a version of Python supported by scikit-image (see pyproject.toml <https://github.com/scikit-image/scikit-image/blob/main/pyproject.toml#L14>_).

First, fork the scikit-image repository on GitHub <https://github.com/scikit-image/scikit-image/fork>_. Then clone your fork locally and set an upstream remote to point to the original scikit-image repository:

.. note::

We use ``[email protected]`` below; if you don't have SSH keys setup, use
``https://github.com`` instead.

.. code-block:: sh

git clone [email protected]:YOURUSERNAME/scikit-image cd scikit-image git remote add upstream [email protected]:scikit-image/scikit-image

All commands below are run from within the cloned scikit-image directory.

.. _build-env-setup:

Build environment setup

Set up a Python development environment tailored for scikit-image. Here we provide instructions for two popular environment managers: venv (pip) and conda (miniforge).

venv ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: sh

Create a virtualenv named `skimage-dev` that lives outside of the repository.

One common convention is to place it inside an `envs` directory under your home directory:

mkdir ~/envs python -m venv ~/envs/skimage-dev

Activate it

(On Windows, use `skimage-dev\Scripts\activate`)

source ~/envs/skimage-dev/bin/activate

Install development dependencies

pip install -r requirements.txt pip install -r requirements/build.txt

Install scikit-image in editable mode. In editable mode,

scikit-image will be recompiled, as necessary, on import.

spin install -v

.. tip::

The above installs scikit-image into your environment, which makes
it accessible to IDEs, IPython, etc.
This is not strictly necessary; you can also build with:

.. code-block:: sh

    spin build

In that case, the library is not installed, but is accessible via
``spin`` commands, such as ``spin test``, ``spin ipython``, ``spin run``,
etc.

conda ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

We recommend installing conda using miniforge <https://github.com/conda-forge/miniforge>_, an alternative to Anaconda without licensing costs.

After installing miniforge:

.. code-block:: sh

Create a conda environment with required dependencies

conda env create -f environment.yml

Activate it

conda activate skimage-dev

Install scikit-image in editable mode. In editable mode,

scikit-image will be recompiled, as necessary, on import.

spin install -v

.. tip::

The above installs scikit-image into your environment, which makes
it accessible to IDEs, IPython, etc.
This is not strictly necessary; you can also build with:

.. code-block:: sh

    spin build

In that case, the library is not installed, but is accessible via
``spin`` commands, such as ``spin test``, ``spin ipython``, ``spin run``,
etc.

Testing

Run the complete test suite:

.. code-block:: sh

spin test

Or run a subset of tests:

.. code-block:: sh

Run tests in a given file

spin test skimage/morphology/tests/test_gray.py

Run tests in a given directory

spin test skimage/morphology

Run tests matching a given expression

spin test -- -k local_maxima

Adding a feature branch

When contributing a new feature, do so via a feature branch.

First, fetch the latest source:

.. code-block:: sh

git switch main git pull upstream main

Create your feature branch:

.. code-block:: sh

git switch --create my-feature-name

Using an editable install, scikit-image will rebuild itself as necessary. If you are building manually, rebuild with::

.. code-block:: sh

spin build

Repeated, incremental builds usually work just fine, but if you notice build problems, rebuild from scratch using:

.. code-block:: sh

spin build --clean

Platform-specific notes

Windows

Building scikit-image on Windows is done as part of our continuous integration testing; the steps are shown in this Azure Pipeline_.

.. _Azure Pipeline: https://github.com/scikit-image/scikit-image/blob/main/azure-pipelines.yml

Debian and Ubuntu

Install suitable compilers prior to library compilation:

.. code-block:: sh

sudo apt-get install build-essential

Full requirements list

Build Requirements

.. include:: ../../../requirements/build.txt :literal:

Runtime Requirements

.. include:: ../../../requirements/default.txt :literal:

Test Requirements

.. include:: ../../../requirements/test.txt :literal:

Documentation Requirements

.. include:: ../../../requirements/docs.txt :literal:

Developer Requirements

.. include:: ../../../requirements/developer.txt :literal:

Data Requirements

The full selection of demo datasets is only available with the following installed:

.. include:: ../../../requirements/data.txt :literal:

Optional Requirements

You can use scikit-image with the basic requirements listed above, but some functionality is only available with the following installed:

Matplotlib <https://matplotlib.org>__ Used in various functions, e.g., for drawing, segmenting, reading images.
Dask <https://dask.org/>__ The dask module is used to parallelize certain functions.

More rarely, you may also need:

PyAMG <https://pyamg.org/>__ The pyamg module is used for the fast cg_mg mode of random walker segmentation.
Astropy <https://www.astropy.org>__ Provides FITS I/O capability.
SimpleITK <http://www.simpleitk.org/>__ Optional I/O plugin providing a wide variety of formats <https://itk.org/Wiki/ITK_File_Formats>__. including specialized formats used in biomedical imaging.

.. include:: ../../../requirements/optional.txt :literal:

Help with contributor installation

See Additional help <#additional-help>_ above.

Installing scikit-image

Installing scikit-image

Supported platforms

Version check

Installation via pip and conda

Update pip

Install scikit-image

System package managers

Downloading all demo datasets

Additional help

Installing scikit-image for contributors

Build environment setup

Create a virtualenv named skimage-dev that lives outside of the repository.

One common convention is to place it inside an envs directory under your home directory:

Activate it

(On Windows, use skimage-dev\Scripts\activate)

Install development dependencies

Install scikit-image in editable mode. In editable mode,

scikit-image will be recompiled, as necessary, on import.

Create a conda environment with required dependencies

Activate it

Install scikit-image in editable mode. In editable mode,

scikit-image will be recompiled, as necessary, on import.

Testing

Run tests in a given file

Run tests in a given directory

Run tests matching a given expression

Adding a feature branch

Platform-specific notes

Full requirements list

Help with contributor installation

Create a virtualenv named `skimage-dev` that lives outside of the repository.

One common convention is to place it inside an `envs` directory under your home directory:

(On Windows, use `skimage-dev\Scripts\activate`)