Skip to main content

Mesa: Agent-based modeling in Python

CI/CD GitHub Actions build status Coverage status
Package PyPI - Version PyPI - Downloads PyPI - Python Version
Meta linting - Ruff code style: black Hatch project SPEC 0 — Minimum Supported Dependencies
Chat chat

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

  • Modular components
  • Browser-based visualization
  • Built-in tools for analysis
  • Example model library

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:

  • It mounts the mesa root directory (relative to the docker-compose.yml file) into /opt/mesa and runs pip install -e on that directory so your changes to mesa should be reflected in the running container.
  • It binds the docker container's port 8765 to your host system's port 8765 so you can interact with the running model as usual by visiting localhost:8765 on your browser

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

  • make sure that your model folder is inside the folder containing the docker-compose.yml file
  • change the MODEL_DIR variable in docker-compose.yml to point to the path of your model
  • make sure that the model folder contains an app.py file

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

  • Join our Matrix chat room in which questions, issues, and ideas can be (informally) discussed.
  • Come to a monthly dev session (you can find dev session times, agendas and notes on Mesa discussions).
  • Just check out the code on GitHub.

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.

Metadata

Release files for Mesa 3.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for Mesa 3.1.3
File Size Uploaded Provenance Actions
mesa-3.1.3.tar.gz 2.5 MB With provenance Details for mesa-3.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for Mesa 3.1.3
File Interpreter ABI Platform Actions
mesa-3.1.3-py3-none-any.whl Python 3 none any Details for mesa-3.1.3-py3-none-any.whl

Total release size: 2.7 MB

Release files / mesa-3.1.3.tar.gz

Download URL mesa-3.1.3.tar.gz
Size 2.5 MB
Tags Source
SHA-256 checksum
How to use checksums
b0cf64ddf924d11314dce3c5f092123aca70f8aa11ecf5c73caec83081804bbf
BLAKE2b-256 checksum
How to use checksums
bd56a2f1802112a431833f166b42da439fcafa5802c3d3c209046af925680eb0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.0.1 CPython/3.12.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 11, 2025.

Transparency log

Release files / mesa-3.1.3-py3-none-any.whl

Download URL mesa-3.1.3-py3-none-any.whl
Size 176.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
29312f5e2c136022f10b51068ee4f7d3e09917d7f8e3f89d9870c0c831b07c9f
BLAKE2b-256 checksum
How to use checksums
93245e446e9b8d2190b58388fa5f97f53d2be7a22ed2a43fff7e87b77042f7df
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.0.1 CPython/3.12.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 11, 2025.

Transparency log

Security for Mesa 3.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mesa-3.1.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 11, 2025.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.1.3 This release

2 release files Full provenance

0.7.8

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page