https://github.com/projectmesa/mesa
Mesa is an open-source Python library for agent-based modeling, ideal for simulating complex systems and exploring emergent behaviors.
https://github.com/projectmesa/mesa
agent-based-modeling agent-based-simulation complex-systems complexity-analysis gis mesa modeling-agents simulation simulation-environment simulation-framework spatial-models
Last synced: 6 days ago
JSON representation
Mesa is an open-source Python library for agent-based modeling, ideal for simulating complex systems and exploring emergent behaviors.
- Host: GitHub
- URL: https://github.com/projectmesa/mesa
- Owner: projectmesa
- License: apache-2.0
- Created: 2014-09-19T21:16:30.000Z (over 10 years ago)
- Default Branch: main
- Last Pushed: 2025-03-30T07:58:56.000Z (15 days ago)
- Last Synced: 2025-04-01T19:09:39.292Z (13 days ago)
- Topics: agent-based-modeling, agent-based-simulation, complex-systems, complexity-analysis, gis, mesa, modeling-agents, simulation, simulation-environment, simulation-framework, spatial-models
- Language: Python
- Homepage: https://mesa.readthedocs.io
- Size: 13.6 MB
- Stars: 2,868
- Watchers: 94
- Forks: 976
- Open Issues: 158
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
Awesome Lists containing this project
- awesome-sciml - projectmesa/mesa: Mesa is an agent-based modeling framework in Python
README
# Mesa: Agent-based modeling in Python
| | |
|---------| --- |
| CI/CD | [](https://github.com/projectmesa/mesa/actions) [](https://codecov.io/gh/projectmesa/mesa) |
| Package | [](https://pypi.org/project/Mesa/) [](https://pypi.org/project/Mesa/) [](https://pypi.org/project/Mesa/) |
| Meta | [](https://github.com/astral-sh/ruff) [](https://github.com/psf/black) [](https://github.com/pypa/hatch) [](https://scientific-python.org/specs/spec-0000/) |
| Chat | [](https://matrix.to/#/#project-mesa:matrix.org) |
| Cite | [](https://doi.org/10.21105/joss.07668) |
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.
*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, run:
``` bash
pip install -U mesa
```
Starting with Mesa 3.0, we don't install all our dependencies anymore by default.
```bash
# You can customize the additional dependencies you need, if you want. Available are:
pip install -U mesa[network,viz]
# This is equivalent to our recommended dependencies:
pip install -U mesa[rec]
# To install all, including developer, dependencies:
pip install -U mesa[all]
```
You can also use `pip` to install the latest GitHub version:
``` bash
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:
``` bash
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:
- [Intro to Mesa Tutorial](http://mesa.readthedocs.org/en/stable/tutorials/intro_tutorial.html) (An introductory model, the Boltzmann
Wealth Model, for beginners or those new to Mesa.)
- [Visualization Tutorial](https://mesa.readthedocs.io/stable/tutorials/visualization_tutorial.html) (An introduction into our Solara visualization)
- [Complexity Explorer Tutorial](https://www.complexityexplorer.org/courses/172-agent-based-models-with-python-an-introduction-to-mesa) (An advanced-beginner model,
SugarScape with Traders, with instructional videos)
- [Mesa Examples](https://github.com/projectmesa/mesa-examples) (A repository of seminal ABMs using Mesa and
examples of employing specific Mesa Features)
- [Docs](http://mesa.readthedocs.org/) (Mesa's documentation, API and useful snippets)
- [Development version docs](https://mesa.readthedocs.io/latest/) (the latest version docs if you're using a pre-release Mesa version)
- [Discussions](https://github.com/projectmesa/mesa/discussions) (GitHub threaded discussions about Mesa)
- [Matrix Chat](https://matrix.to/#/#project-mesa:matrix.org) (Chat Forum via Matrix to talk about Mesa)
## 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](https://docs.docker.com/compose/install/) and then, in the
folder containing the Mesa Git repository, you run:
``` bash
$ 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](https://matrix.to/#/#project-mesa:matrix.org) 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](https://github.com/projectmesa/mesa/discussions)).
> - Just check out the code on [GitHub](https://github.com/projectmesa/mesa/).
If you run into an issue, please file a [ticket](https://github.com/projectmesa/mesa/issues) 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](https://github.com/projectmesa/mesa/issues) or
join a dev session (see [Mesa discussions](https://github.com/projectmesa/mesa/discussions)). A feature is most likely
to be added if you build it!
Don't forget to checkout the [Contributors guide](https://github.com/projectmesa/mesa/blob/main/CONTRIBUTING.md).
## Citing Mesa
To cite Mesa in your publication, you can refer to our peer-reviewed article in the Journal of Open Source Software (JOSS):
- ter Hoeven, E., Kwakkel, J., Hess, V., Pike, T., Wang, B., rht, & Kazil, J. (2025). Mesa 3: Agent-based modeling with Python in 2025. Journal of Open Source Software, 10(107), 7668. https://doi.org/10.21105/joss.07668
Our [CITATION.cff](https://github.com/projectmesa/mesa/blob/main/CITATION.cff) can be used to generate APA, BibTeX and other citation formats.