Installation

Most users of ixmp will have it installed automatically as a dependency of message_ix, for instance by following the Quick install instructions.

Important

If that is the case, you do not need to also follow these instructions.

The sections below cover other use cases, such as:

Using ixmp alone —that is, without message_ix, perhaps with other models or frameworks.
Installing ixmp from source for development purposes, for instance for use with a source install of message_ix.

They correspond to sections of the MESSAGEix Advanced installation guide and reference its contents. They omit extra background information and discussion found in that guide. Be sure that you have the prerequisite skills and knowledge; these include specific points of knowledge that are necessary to understand these instructions and choose among different installation options.

To use ixmp from R, see Install R and reticulate in the MESSAGEix documentation.

Install system dependencies 

Read and follow each of these sections of the MESSAGEix Advanced installation guide:

Install `ixmp`

Choose pip or conda

Read Choose pip or conda in the the MESSAGEix Advanced installation guide.

Whichever option you choose, please skip over the unrelated sections below.

Create and activate a virtual environment 

Read and follow Create and activate a virtual environment.

Then, according to your choice above, follow either “Use pip” or “Use conda” below.

Use pip

Choose optional dependencies 

Optional dependencies (also called “extra requirements”) are gathered in groups. The example commands below include a string like [docs]. This implies four of the five available groups of extra requirements for ixmp:

docs includes packages required to build this documentation locally, including ixmp[tests] and all its requirements,
ixmp4 includes packages required to use the IXMP4Backend,
report includes packages required to use the built-in reporting features of ixmp,
tests includes packages required to run the test suite, including ixmp[ixmp4], ixmp[report], ixmp[tutorial] and all the requirements in those groups, and
tutorial includes packages required to run the tutorials.

Install the latest release from PyPI 

Install ixmp [1]:
```
pip install ixmp[docs]
```

At this point, installation is complete.

Install from GitHub 

Run the following. Replace <ref> with a specific Git reference such as a branch name (for instance, the main development branch, or a branch associated with a pull request), a tag, or a commit hash:
```
pip install git+ssh://git@github.com:iiasa/ixmp.git@<ref>[docs]
```
git+ssh:// assumes that you use SSH to authenticate to GitHub, which we recommend. If you instead use other methods, then run:
```
pip install git+https://github.com/iiasa/ixmp.git@<ref>[docs]
```

At this point, installation is complete.

Install from a git clone of the source code 

See the corresponding section in the MESSAGEix Advanced installation guide for further details about editable installs, registering a GitHub account, and using a fork.

Clone either the main repository, or your fork; using the Github Desktop client, or the command line:
```
git clone git@github.com:iiasa/ixmp.git

# or:
git clone git@github.com:<user>/ixmp.git
```
Navigate to the ixmp directory created by git clone in step (2). Run the following [1]:
```
pip install --editable .[docs]
```

At this point, installation is complete.

Use conda

Configure conda to install ixmp from the conda-forge ‘channel’:
```
conda config --prepend channels conda-forge
```
Install and configure the mamba solver, which is faster and more reliable than conda’s default solver:
```
conda install conda-libmamba-solver
conda config --set solver libmamba
```
Create a new conda environment and activate it. This step is required if using Anaconda, but optional if using Miniconda. This example uses the name ixmp-env, but you can use any name of your choice:
```
conda create --name ixmp-env
conda activate ixmp-env
```
Install the ixmp package into the current environment (either ixmp-env, or another name from the previous step):
```
conda install ixmp
```

At this point, installation is complete.

Troubleshooting 

To check that you have all dependencies installed, or when reporting issues, run the following:

ixmp show-versions