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, withoutmessage_ix
, perhaps with other models or frameworks.Installing
ixmp
from source for development purposes, for instance for use with a source install ofmessage_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, includingixmp[tests]
and all its requirements,ixmp4
includes packages required to use theIXMP4Backend
,report
includes packages required to use the built-in reporting features ofixmp
,tests
includes packages required to run the test suite, includingixmp[ixmp4]
,ixmp[report]
,ixmp[tutorial]
and all the requirements in those groups, andtutorial
includes packages required to run the tutorials.
Install the latest release from PyPI
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, themain
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 (eitherixmp-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