Skip to content

Latest commit

 

History

History
507 lines (345 loc) · 16.3 KB

INSTALL.rst

File metadata and controls

507 lines (345 loc) · 16.3 KB
Raw

Installing scikit-image

How you should install scikit-image depends on your needs and skills:

Supported platforms

  • Windows 64-bit on x86 processors
  • Mac OS X on x86 processors
  • Linux 64-bit on x86 processors

For information on other platforms, see other platforms.

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:

import skimage
print(skimage.__version__)

or, from the command line:

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.

Scientific Python distributions

In a single install these give you Python, scikit-image and libraries it depends on, and other useful scientific packages. They install into an isolated environment, so they won't conflict with any existing installed programs.

Drawbacks are that the install can be large and you may not get the most recent scikit-image.

We recommend one of these distributions:

When using the scikit-image documentation, make sure it's for the version you've installed (see Version check above).

Installation via pip and conda

These install only scikit-image and its dependencies; pip has an option to include related packages.

pip

Prerequisites to a pip install: You're able to use your system's command line to install packages and are using a virtual environment (any of several).

While it is possible to use pip without a virtual environment, it is not advised: virtual environments create a clean Python environment that does not interfere with any existing system installation, can be easily removed, and contain only the package versions your application needs. They help avoid a common challenge known as dependency hell.

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

# Update pip
python -m pip install -U pip
# Install scikit-image
python -m pip install -U scikit-image

To include a selection of other scientific Python packages that expand scikit-image's capabilities to include, e.g., parallel processing, you can install the package scikit-image[optional]:

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

Warning

Please do not use the command sudo and pip together as pip may overwrite critical system libraries which may require you to reinstall your operating system.

conda

Miniconda is a bare-essentials version of the Anaconda package; you'll need to install packages like scikit-image yourself. Like Anaconda, it installs Python and provides virtual environments.

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

conda install scikit-image

System package managers

Using a package manager (yum, apt-get, etc.) to install scikit-image or other Python packages is not your best option:

  • You're likely to get an older version.
  • You'll probably want to make updates and add new packages outside of the package manager, leaving you with the same kind of dependency conflicts you see when using pip without a virtual environment.
  • There's an added risk because operating systems use Python, so if you make system-wide Python changes (installing as root or using sudo), you can break the operating system.

Downloading all demo datasets

Some of the data used in our examples is hosted online and is not installed by default by the procedures explained above. Data are downloaded once, at the first call, but this requires an internet connection. If you prefer downloading all the demo datasets to be able to work offline, you can run this command:

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

or call download_all() in your favourite interactive Python environment (IPython, Jupyter notebook, ...).

Other platforms

We still support Windows 32-bit on x86 processors but urge switching to Windows 64-bit.

Unsupported platforms include:

  1. Linux on 32-bit x86 processors.
  2. Linux on 32-bit on ARM processors (Raspberry Pi running Raspbian):
  3. Linux on 64-bit ARM processors (Nvidia Jetson):

Although these platforms lack official support, many of the core developers have experience with them and can help with questions.

If you want to install on an unsupported platform, try building from source.

Tell us which other platforms you'd like to see scikit-image on! We are very interested in how scikit-image gets used.

If you'd like to package scikit-image for an as-yet-unsupported platform, reach out on GitHub.

Additional help

If you still have questions, reach out through

To suggest a change in these instructions, please open an issue on GitHub.

Installing scikit-image for contributors

We are assuming that you have a default Python environment already configured on your computer and that you intend to install scikit-image inside of it.

We also make a few more assumptions about your system:

  • You have a C compiler set up.
  • You have a C++ compiler set up.
  • You are running a version of Python compatible with our system as listed in our setup.py file.
  • You've cloned the git repository into a directory called scikit-image. You have set up the upstream remote to point to our repository and origin to point to your fork.

This directory contains the following files:

scikit-image
├── asv.conf.json
├── azure-pipelines.yml
├── benchmarks
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.rst
├── CONTRIBUTORS.txt
├── doc
├── INSTALL.rst
├── LICENSE.txt
├── Makefile
├── MANIFEST.in
├── README.md
├── RELEASE.txt
├── requirements
├── requirements.txt
├── setup.cfg
├── setup.py
├── skimage
├── TODO.txt
├── tools

All commands below are assumed to be running from the scikit-image directory containing the files above.

Build environment setup

Once you've cloned your fork of the scikit-image repository, you should set up a Python development environment tailored for scikit-image. You may choose the environment manager of your choice. Here we provide instructions for two popular environment managers: venv (pip based) and conda (Anaconda or Miniconda).

venv

When using venv, you may find the following bash commands useful:

# Create a virtualenv named ``skimage-dev``
python -m venv skimage-dev
# Activate it. On Linux and MacOS:
source skimage-dev/bin/activate
# Make sure that pip is up to date
pip install --upgrade pip
# Install all development and runtime dependencies of scikit-image
pip install -r <(cat requirements/*.txt)
# Build and install scikit-image from source
pip install -e . -vv
# Test your installation
pytest skimage

On Windows, please use skimage-dev\Scripts\activate on the activation step.

conda

When using conda for development, we recommend adding the conda-forge channel for the most up-to-date version of many dependencies. Some dependencies we use (for testing and documentation) are not available from the default Anaconda channel. Please follow the official conda-forge installation instructions before you get started.

# Create a conda environment named ``skimage-dev``
conda create --name skimage-dev
# Activate it
conda activate skimage-dev
# Install major development and runtime dependencies of scikit-image
conda install `for i in requirements/{default,build,test}.txt; do echo -n " --file $i "; done`
# Install scikit-image from source
pip install -e . -vv
# Test your installation
pytest skimage

Updating the installation

When updating your installation, it is often necessary to recompile submodules that have changed. Do so with the following commands:

# Grab the latest source
git checkout main
git pull upstream main
# Update the installation
pip install -e . -vv

Testing

scikit-image has an extensive test suite that ensures correct execution on your system. The test suite must pass before a pull request can be merged, and tests should be added to cover any modifications to the code base.

We use the pytest testing framework, with tests located in the various skimage/submodule/tests folders.

Our testing requirements are listed below:

Run all tests using:

pytest skimage

Or the tests for a specific submodule:

pytest skimage/morphology

Or tests from a specific file:

pytest skimage/morphology/tests/test_gray.py

Or a single test within that file:

pytest skimage/morphology/tests/test_gray.py::test_3d_fallback_black_tophat

Use --doctest-modules to run doctests. For example, run all tests and all doctests using:

pytest --doctest-modules skimage

Warnings during testing phase

Scikit-image tries to catch all warnings in its development builds to ensure that crucial warnings from dependencies are not missed. This might cause certain tests to fail if you are building scikit-image with versions of dependencies that were not tested at the time of the release. To disable failures on warnings, export the environment variable SKIMAGE_TEST_STRICT_WARNINGS with a value of 0 or False and run the tests:

export SKIMAGE_TEST_STRICT_WARNINGS=False
pytest --pyargs skimage

Platform-specific notes

Windows

If you experience the error Error:unable to find vcvarsall.bat it means that your computer does not have recommended compilers for Python. You can either download and install Windows compilers from here or use MinGW compilers . If using MinGW, make sure to correctly configure distutils by modifying (or create, if not existing) the configuration file distutils.cfg (located for example at C:\Python26\Lib\distutils\distutils.cfg) to contain:

[build]
 compiler=mingw32

A run-through of the compilation process for Windows is included in our setup of Azure Pipelines (a continuous integration service).

Debian and Ubuntu

Install suitable compilers:

sudo apt-get install build-essential

Full requirements list

Build Requirements

Runtime Requirements

Test Requirements

Documentation Requirements

Optional Requirements

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

  • SimpleITK
    Optional I/O plugin providing a wide variety of formats. including specialized formats using in medical imaging.
  • Astropy
    Provides FITS I/O capability.
  • PyAMG
    The pyamg module is used for the fast cg_mg mode of random walker segmentation.
  • Dask
    The dask module is used to speed up certain functions.

Extra Requirements

These requirements have been included as a convenience, but are not widely installable through PyPI on our supported platforms. As such, we keep them in a separate list for more advanced members of our community to install.

Help with contributor installation

See Additional help above.