Installing

Iris can be installed using conda or pip.

Note

Iris is currently supported and tested against Python 3.10, 3.11 and 3.12 running on Linux. We do not currently actively test on other platforms such as Windows or macOS.

Windows 10 now has support for Linux distributions via WSL (Windows Subsystem for Linux). This is a great option to get started with Iris for users and contributors. Be aware that we do not currently test against any WSL distributions.

Note

This documentation was built using Python 3.12.2.

Installing a Released Version Using Conda

To install Iris using conda, you must first download and install conda, for example from https://docs.conda.io/en/latest/miniconda.html.

Once conda is installed, you can install Iris using conda with the following command:

conda install -c conda-forge iris

If you wish to run any of the code in the gallery you will also need the Iris sample data. This can also be installed using conda:

conda install -c conda-forge iris-sample-data

Further documentation on using conda and the features it provides can be found at https://docs.conda.io/projects/conda/en/latest/index.html.

Installing a Released Version Using Pip

Iris is also available from https://pypi.org/ so can be installed with pip:

pip install scitools-iris

If you wish to run any of the code in the gallery you will also need the Iris sample data. This can also be installed using pip:

pip install iris-sample-data

Installing a Development Version from a Git Checkout

The latest Iris source release is available from SciTools/iris.

For instructions on how to obtain the Iris project source from GitHub see Making Your own Copy (fork) of Iris and Set up Your Fork for instructions.

Once conda is installed, you can create a development environment for Iris using conda and then activate it. The example commands below assume you are in the root directory of your local copy of Iris:

conda env create --force --file=requirements/iris.yml
conda activate iris-dev

Note

The --force option, used when creating the environment, first removes any previously existing iris-dev environment of the same name. This is particularly useful when rebuilding your environment due to a change in requirements.

The requirements/iris.yml file defines the Iris development conda environment name and all the relevant top level conda-forge package dependencies that you need to code, test, and build the documentation. If you wish to minimise the environment footprint, simply remove any unwanted packages from the requirements file e.g., if you don’t intend to run the Iris tests locally or build the documentation, then remove all the packages from the testing and documentation sections.

Note

The requirements/iris.yml file will always use the latest Iris tested Python version available. For all Python versions that are supported and tested against by Iris, view the contents of the requirements directory.

Finally you need to run the command to configure your environment to find your local Iris code. From your Iris directory run:

pip install --no-deps --editable .

Running the Tests

To ensure your setup is configured correctly you can run the test suite using the command:

pytest

For more information see Testing Iris in a Manually Created Environment.

Custom Site Configuration

The default site configuration values can be overridden by creating the file iris/etc/site.cfg. For example, the following snippet can be used to specify a non-standard location for your dot executable:

[System]
dot_path = /usr/bin/dot

An example configuration file is available in iris/etc/site.cfg.template. See iris.config() for further configuration options.