Mesa: a Python library for agent-based modeling, from grid to browser

What Mesa solves, and who ends up using it

Agent-based models are awkward to write from scratch. You need a container for agents, a way to schedule them, a spatial structure if agents occupy positions, and some way to look at what happened. Mesa supplies those pieces as Python objects so the model author writes the rules and not the scaffolding. The README states the goal plainly: to be the Python-based alternative to NetLogo, Repast or MASON.

That framing tells you who it is for. If your work already lives in Python, the appeal is that an agent's decision rule can call scipy, a results table can land in pandas, and the whole model can sit inside pytest. If you would rather build a model by dragging blocks in a graphical environment, Mesa is a step backwards, because everything is code.

The package metadata classifies it under Scientific/Engineering and lists Python 3.12, 3.13 and 3.14 as supported, with requires-python set to >=3.12. That is a narrow band compared with libraries that still support 3.9, and it matters if you are pinned to an older interpreter.

How a model is put together: agents, schedulers, grids, visualizer

The README describes the library as built from modular components such as spatial grids and agent schedulers, with the option to substitute your own implementations. That is the architecture in one sentence: Mesa does not impose a simulation loop you cannot see. You define an agent class, you define a model class that owns the agents, and you choose a scheduler that determines the order in which agents act. The docs point to the Getting Started tutorials for the concrete shape of that loop.

Spatial structure is a separate choice rather than a built-in assumption, which is why the topics list includes gis alongside agent-based-modeling. A model with no space at all, a grid-based model and a network-based model are all the same kind of program to Mesa; only the components differ.

Visualization is also a component, not a core dependency. Since Mesa 3.0 the README says dependencies are no longer all installed by default, and the viz extra is what brings in matplotlib, solara, altair and starlette. The screenshot in the README shows the WolfSheep model rendered in a browser window or in Jupyter, and the README links an online demo. The practical consequence is that a headless batch run does not have to drag a web stack along with it.

Installing Mesa and running a first model

The README gives the stable install as a single pip command. Run it in a virtual environment on Python 3.12 or newer, and pip should resolve numpy, pandas, tqdm and scipy as core dependencies.

pip install -U mesa

The README warns that from Mesa 3.0 onward the extra dependencies are not installed by default. If you want the visualization stack and network support, install the extras explicitly. The rec extra is described in the README as equivalent to the recommended set.

pip install -U "mesa[rec]"

If you need a specific combination instead, the README lists network and viz as the available groups, and all for everything including developer dependencies.

pip install -U "mesa[network,viz]"

For work on Mesa itself, or to track main, the README shows an editable install straight from GitHub. This is the form you want if you intend to patch the library and see the change immediately.

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

There is also a Docker path. The README says that from the folder containing the Mesa Git repository, docker compose up runs the Schelling model as an example, and that the compose file mounts the mesa root directory into /opt/mesa, runs pip install -e on it, and binds container port 8765 to host port 8765.

docker compose up

After either route, the README points to the Getting Started tutorials as the place to build a basic model. For a model developer running their own model in Docker, the README requires the model folder to sit inside the folder containing docker-compose.yml, to contain an app.py file, and to be referenced by changing the MODEL_DIR variable in docker-compose.yml; after that, docker compose up -d makes it reachable at localhost:8765. The README does not document what happens if app.py is missing or the port is already taken.

Where Mesa gets in the way

The most visible limitation is version 4. The README opens by saying Mesa 4 is in active development and directs readers to the pre-releases and an issue tracker link. The release list shows v4.0.0a0 sitting alongside v3.5.1 and v3.5.0, so the alpha is published but the stable line is still 3.x. Anyone reading about Mesa 4 features should check which version they installed, because pip install -U mesa and pip install -U --pre mesa are different commands with different results.

The second constraint is the dependency split. It is a deliberate trade-off, and a reasonable one, but it means a copied snippet that imports a visualization component will fail on a plain install until the viz or rec extra is added. The README documents the extras; it does not document the error you get when you forget them.

Third, the project's own metadata labels the development status as Alpha. That is a statement about API stability, not about whether the code works. If your model is going into a paper or a production pipeline, pin the version you validated rather than tracking the latest release.

Finally, the name is a poor search term. Searching for Mesa returns restaurants, a city in Arizona and a Star Wars character long before it returns a Python simulation library, which is a real cost when you are trying to find an answer at two in the morning.

Mesa against NetLogo, Repast and MASON

The README names the comparison itself: Mesa aims to be the Python-based alternative to NetLogo, Repast or MASON. The difference is not features, it is the environment. NetLogo gives you a dedicated language and an IDE with a built-in interface builder; you write the model in NetLogo and you get the controls and plots without touching a web framework. Repast and MASON are the Java-side equivalents, with MASON aimed at speed and Repast at a broader modeling toolkit.

Mesa makes the opposite trade. You lose the purpose-built environment and you gain everything in the Python ecosystem: numpy arrays inside agent state, pandas for the results, pytest for the rules, and whatever plotting or statistics library you already trust. The visualization is browser-based rather than an IDE panel, which is why the Docker instructions end at localhost:8765.

There is no benchmark published in the repository comparing Mesa's execution speed with any of these, so treat any performance comparison you read elsewhere as unverified. The honest distinction is workflow, not throughput.

Maintenance, releases and the licence

The repository is not archived, and the last push was on 2026-09-23. The release history shows v3.5.0 on 2026-02-15, v4.0.0a0 on 2026-03-14 and v3.5.1 on 2026-03-15, so the stable line is receiving patch releases while the 4.0 alpha is developed in parallel. The README also links a Google Summer of Code 2026 guide and monthly dev sessions, which indicates an active contributor process rather than a frozen codebase.

Upgrade cost is the thing to plan for. Because the project is at Alpha development status and a major version is in flight, upgrading across the 3.x to 4.x boundary is where breakage will concentrate. The README does not document a migration path or a rollback procedure, so the safe approach is to pin the version in your own project and read HISTORY.md before moving.

On licensing: the repository carries an Apache-2.0 licence, and pyproject.toml declares the same under the project metadata. Apache-2.0 is permissive and includes an explicit patent grant, but it also carries notice and attribution obligations. If you redistribute Mesa inside a product, read the LICENSE and NOTICE files in the repository rather than relying on a summary, and get legal advice if the obligations affect your distribution.

Editorial conclusion

Mesa fits researchers and analysts who already work in Python and want an agent-based model they can debug, test and extend with numpy and pandas. It is the wrong tool if you need a point-and-click environment with no code, or if you need Mesa 4 features now, since that line is still pre-release. Before committing, verify that your Python is 3.12 or newer, decide whether you need the rec extra for solara and networkx, and check the Getting Started tutorial against the version you actually install.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. mesa/mesa on GitHub
3. Project website
4. README
5. Releases