Home

Awesome

Mesa: Agent-based modeling in Python

CI/CDGitHub Actions build status Coverage status
PackagePyPI - Version PyPI - Downloads PyPI - Python Version
Metalinting - Ruff code style: black Hatch project SPEC 0 — Minimum Supported Dependencies
Chatchat

Mesa allows users to quickly create agent-based models using built-in core components (such as spatial grids and agent schedulers) or customized implementations; visualize them using a browser-based interface; and analyze their results using Python's data analysis tools. Its goal is to be the Python-based alternative to NetLogo, Repast, or MASON.

A screenshot of the WolfSheep Model in Mesa

Above: A Mesa implementation of the WolfSheep model, this can be displayed in browser windows or Jupyter.

Features

Using Mesa

To install our latest stable release (3.0.x), run:

pip install -U mesa

To install our latest pre-release, run:

pip install -U --pre mesa

Starting with Mesa 3.0, we don't install all our dependencies anymore by default.

# You can customize the additional dependencies you need, if you want. Available are:
pip install -U --pre mesa[network,viz]

# This is equivalent to our recommended dependencies:
pip install -U --pre mesa[rec]

# To install all, including developer, dependencies:
pip install -U --pre mesa[all]

You can also use pip to install the latest GitHub version:

pip install -U -e git+https://github.com/projectmesa/mesa@main#egg=mesa

Or any other (development) branch on this repo or your own fork:

pip install -U -e git+https://github.com/YOUR_FORK/mesa@YOUR_BRANCH#egg=mesa

Resources

For resources or help on using Mesa, check out the following:

Running Mesa in Docker

You can run Mesa in a Docker container in a few ways.

If you are a Mesa developer, first install Docker Compose and then, in the folder containing the Mesa Git repository, you run:

$ docker compose up
# If you want to make it run in the background, you instead run
$ docker compose up -d

This runs the Schelling model, as an example.

With the docker-compose.yml file in this Git repository, the docker compose up command does two important things:

If you are a model developer that wants to run Mesa on a model, you need to:

Then, you just need to run docker compose up -d to have it accessible from localhost:8765.

Contributing to Mesa

Want to join the Mesa team or just curious about what is happening with Mesa? You can...

If you run into an issue, please file a ticket for us to discuss. If possible, follow up with a pull request.

If you would like to add a feature, please reach out via ticket or join a dev session (see Mesa discussions). A feature is most likely to be added if you build it!

Don't forget to checkout the Contributors guide.

Citing Mesa

To cite Mesa in your publication, you can use the CITATION.bib.