Ensure you have first read the :doc:`prerequisites <prereqs>` for understanding and using |MESSAGEix|. These include specific points of knowledge that are necessary to understand these instructions and choose among different installation options.
|MESSAGEix| requires GAMS.
Download GAMS for your operating system; either the latest version or, for users not familiar with GAMS licenses, version 29 (see note below).
Run the installer.
Ensure that the
PATHenvironment variable on your system includes the path to the GAMS program:on Windows, in the GAMS installer…
- Check the box labeled “Use advanced installation mode.”
- Check the box labeled “Add GAMS directory to PATH environment variable” on the Advanced Options page.
on macOS, in the GAMS installer…
When prompted to specify the "Installation Type" (step 3 of the installation process), select "Customise".
Check the box labeled "Add GAMS to PATH".
If this option is not available see instructions below.
on other platforms (macOS or Linux), add the following line to a file such as :file:`~/.bash_profile` (macOS), :file:`~/.bashrc`, or :file:`~/.profile`:
$ export PATH=$PATH:/path/to/gams-directory-with-gams-binary
Note
MESSAGE-MACRO and MACRO require GAMS 24.8.1 or later (see :attr:`.MACRO.GAMS_min_version`) The latest version is recommended.
GAMS is proprietary software and requires a license to solve optimization problems. To run both the :mod:`message_ix` and :mod:`ixmp` tutorials and test suites, a “free demonstration” license is required; the free license is suitable for these small models. Versions of GAMS up to version 29 include such a license with the installer; since version 30, the free demo license is no longer included, but may be requested via the GAMS website.
Note
If you only have a license for an older version of GAMS, install both the older and the latest versions.
:meth:`.Reporter.visualize` uses Graphviz, a program for graph visualization. Installing message_ix causes the graphviz Python package to be installed. If you want to use :meth:`.visualize` or run the test suite, the Graphviz program itself must also be installed; otherwise it is optional.
If you install MESSAGEix Using Anaconda, Graphviz is installed automatically via its conda-forge package. For other methods of installation, see the Graphviz download page for downloads and instructions for your system.
After installing GAMS, we recommend that new users install Anaconda, and then use it to install |MESSAGEix|.
Advanced users may choose to install |MESSAGEix| using pip, or from source code (next sections).
If you are not doing this, then skip those sections.
Note
This section is also available as a narrated video on the IIASA YouTube channel. If you are a beginner, you may want to watch the video before attempting the installation yourself.
Install Python via either Miniconda or Anaconda. [1] We recommend the latest version; currently Python 3.10. [2]
Open a command prompt. Windows users should use the “Anaconda Prompt” to avoid issues with permissions and environment variables when installing and using |MESSAGEix|. This program is available in the Windows Start menu after installing Anaconda.
Configure conda to install :mod:`message_ix` from the conda-forge channel [3]:
$ 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
message_env, but you can use any name of your choice:$ conda create --name message_env $ conda activate message_env
Install the
message-ixpackage into the current environment (either e.g.message_env, or another name from step 7) [4]:$ conda install message-ix
Again: at this point, installation is complete.
You do not need to complete the steps in “Using pip” or “From source”.
Go to the section Check that installation was successful.
| [1] | See the conda glossary for the differences between Anaconda and Miniconda, and the definitions of the terms ‘channel’ and ‘environment’ here. |
| [2] | On newer macOS systems with "Apple M1" processors: the Miniconda or Anaconda installers provided for M1 lead to errors in ixmp. Instead, we recommend to use the macOS installers for "x86_64" processors on these systems. See also ixmp issue 473. |
| [3] | The ‘$’ character at the start of these lines indicates that the command text should be entered in the terminal or prompt, depending on the operating system. Do not retype the ‘$’ character itself. |
| [4] | Notice that conda uses the hyphen (‘-’) in package names, different from the underscore (‘_’) used in Python when importing the package. |
Note
When using Anaconda (not Miniconda), steps (5) through (9) can also be performed using the graphical Anaconda Navigator. See the Anaconda Navigator documentation for how to perform the various steps.
pip is Python's default package management system.
If you install Anaconda (step 4, above), then pip is also usable.
pip can also be used when Python is installed directly, without using Anaconda.
Ensure
pipis installed—with Anaconda, or according to the pip documentation.Open a command prompt and run:
$ pip install message_ix[docs,report,tests,tutorial]
The
[docs,report,tests,tutorial]extra requirements ensure additional dependencies are installed.
Install :doc:`ixmp <ixmp:install>` from source.
(Optional) If you intend to contribute changes to |MESSAGEix|, first register a Github account, and fork the message_ix repository. This will create a new repository
<user>/message_ix. (Please also see :doc:`contributing`.)Clone either the main repository, or your fork; using the Github Desktop client, or the command line:
$ git clone [email protected]:iiasa/message_ix.git # or: $ git clone [email protected]:USER/message_ix.git
(Conditional) If you cloned your fork, add the main repository as a remote git repository. This will allow keeping up to date with changes there and importing tags, which also needs to be done for the install tests to succeed:
$ git remote add upstream [email protected]:iiasa/message_ix.git $ git fetch upstream --tags
Open a command prompt in the
message_ixdirectory and type:$ pip install --editable .[docs,report,tests,tutorial]
The
--editableflag ensures that changes to the source code are picked up every timeimport message_ixis used in Python code. The[docs,report,tests,tutorial]extra requirements ensure additional dependencies are installed.(Optional) If you will be using :file:`MESSAGE_master.gms` outside of Python :mod:`message_ix` to run |MESSAGEix|, you will likely modify this file, but will not want to commit these changes to Git. Set the Git “assume unchanged” bit for this file:
$ git update-index --assume-unchanged message_ix/model/MESSAGE_master.gms
To unset the bit, use
--no-assume-unchanged. See the Git documentation for more details.(Optional) If installed from source, run the built-in test suite to check that |MESSAGEix| functions correctly on your system:
$ pytest
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 # Show the list of modelling platforms that have been installed and the path to the database config file # By default, just the local database should appear in the list $ message-ix platform list
The above commands will work as of :mod:`message_ix` 3.0 and in subsequent versions. If an error occurs, this may mean that an older version has been installed and should be updated. To check the current version:
# If installed using conda $ conda list message-ix # If installed using pip $ pip show message-ix
You only need to install R if you want to use :mod:`message_ix` and :mod:`ixmp` from R, rather than from Python.
First, install :mod:`message_ix` using one of the three methods above. Then:
-
Warning
Ensure the the R version installed is either 32- or 64-bit (and >= 3.5.0), consistent with GAMS and Java. Having both 32- and 64-bit versions of R, or mixed 32- and 64-bit versions of different packages, can cause errors.
(Optional) Install IRkernel, which allows running R code in Jupyter notebooks (see the link for instructions).
Next:
See :doc:`rmessageix` for further details.
If you installed :mod:`message_ix` from source, check that the R interface works by using the built-in test suite to run the R tutorial notebooks:
$ pytest -m rmessageix
Error messages like this when running message-ix --platform=default list or when creating a :class:`ixmp.Platform` object (for instance, :py:`ixmp.Platform()` in Python) indicate that :mod:`message_ix` (via :mod:`ixmp` and JPype) cannot find Java on your machine, in particular the Java Virtual Machine (JVM).
There are multiple ways to resolve this issue:
- If you have installed Java manually, ensure that the
JAVA_HOMEenvironment variable is set system-wide; see for example these instructions for Windows users. - If using Anaconda, install the
openjdkpackage in the same environment as themessage-ixpackage. When the Windows Anaconda Prompt is opened,conda activatethen ensures theJAVA_HOMEvariable is correctly set.
To check which JVM will be used by ixmp, run the following in any prompt or terminal:
$ python -c "import jpype; print(jpype.getDefaultJVMPath())"
The package pyam-iamc is one of the "report" extra dependencies of :mod:`message_ix`. These extra dependencies are not installed automatically, but can be installed using:
# If message_ix is installed using pip $ pip install message_ix[report] # or $ pip install pyam-iamc # If message_ix is installed using Anaconda (see note below) $ conda install pyam
Note that this package has the different name on conda-forge versus PyPI: pyam.
The package listed as pyam on PyPI (and not available via Anaconda) is unrelated to :mod:`message_ix`, not compatible with it, and will produce other error messages. If you installed this package accidentally, remove it using:
# If installed using pip $ pip uninstall pyam