Installation

Thank you for using MESSAGEix! We hope this documentation can help you with your modelling journey.

First, choose which install process to use. Use the Quick install steps on this page if all of the following apply:

• You plan to use:

  • …the latest releases of message_ix and ixmp.

  • …Python (not R) to interact with message_ix.

  • …the default terminal for an operating system (OS) like Ubuntu Linux, macOS, or Windows.

  • …a virtual environment to contain your MESSAGEix installation, as we strongly recommend.

• You have already installed on your system:

  • Python (version 3.9 or later) installed, along with either pip or conda;

  • a Java Runtime Environment (JRE) (if not using conda; see here); and

  • GAMS (version 24.8.1 or later).

If any of the above does not apply, instead consult the Advanced installation guide. If the terms above are unfamiliar, you may need to review the Prerequisite knowledge & skills for using MESSAGEix before you proceed. For issues encountered during installation, see “Common issues” in the guide, and further resources linked there.

Quick install

Choose one of the install methods below. Depending on your choice, you should have either pip or conda installed on your system. If in doubt, we recommend pip because it is quick, easy to use and to troubleshoot. (For more considerations, see “Choose pip or conda” in the advanced guide.)

Install the latest release using pip

1. Open a terminal/command prompt.

2. Activate your virtual environment.

3. Run [1]:

   pip install message_ix[docs,report,tests,tutorial]
   

This will install the latest release of MESSAGEix from the Python Package Index (PyPI).

[1]

See “Choose optional dependencies” in the advanced guide for an explanation of the [docs,report,tests,tutorial] extra requirements. See “Graphviz” if you want to use visualize() or run the test suite.

Install the latest release using conda

1. Open a terminal/command prompt.

2. Activate your virtual environment.

3. Configure conda to install message_ix from the conda-forge channel:

   conda config --prepend channels conda-forge
   

4. 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
   

5. Install the message-ix package into the current environment:

   conda install message-ix
   

This will install the latest release of MESSAGEix from conda-forge.

Check that installation was successful

Verify that the version installed corresponds to the latest release by running the following commands on the command line. Show versions of message_ix, ixmp, and key dependencies:

message-ix show-versions

The versions should correspond to the latest version shown on the What’s New page.

Show the list of platforms (~databases) that have been configured and the path to the ixmp config file:

message-ix platform list

See the advanced guide for further details.