Installation

message_ix_models is structured as a Python package, is published to the Python Package Index (PyPI) public repository, and is Free Software. Hence, there are two options for the installation:

From the Python Package Index (PyPI)

This option is only recommended for users who do not wish to make any changes to the source code. This page uses pip; another alternative is uv pip.

Run:

$ pip install message-ix-models[<extra_dependencies>]

From source

Use this option if you intend to make changes to the source code. We value your contributions via pull requests to the main repository. Please consider contributing your changes.

Fork the the main repository. This will create a new repository <user>/message-ix-models.
Clone your fork; using the Github Desktop client, or the command line:
```
$ git clone git@github.com:USER/message-ix-models.git
```
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 git@github.com:iiasa/message-ix-models.git
$ git fetch upstream --tags
```

Inside the message-ix-models directory, run:

$ pip install --editable .[<extra_dependencies>]

Dependencies

The mandatory dependencies of message_ix_models include:

message_ix and thus its upstream dependencies.

The following ‘extras’, or sets of optional dependencies, are available. Without the associated dependencies, the respective modules or features will not work: for example, it is optional to use MESSAGEix-Materials (model.material), but in order to use it the material extra dependencies must be installed.

Per the pip documentation (linked above), they can be installed along with the mandatory dependencies by adding to the package spec. For example, pip install message_data[material,transport] will install the dependencies in those two sets.

bilateralize: For tools.bilateralize.
buildings: For MESSAGEix-Buildings.
docs: Build these documentation pages.
iea-web: For tools.iea.web.
material: For MESSAGEix-Materials (model.material).
migrate: For Migrate code from message_data.
report: For Reporting (report); includes plotnine and xlsxwriter.
tests: Run the test suite.
transport: For MESSAGEix-Transport (model.transport).

See pyproject.toml in the source for the exact contents of each set.

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, message-ix-models, 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
$ mix-models config show

The above commands will work as of message_ix version 3.0 and in subsequent versions. Please read through the output of the mix-models command to understand the different CLI options and what you can do with them.