Mesa

What it is

Mesa is an open-source Python framework for agent-based modelling. Its own README describes the goal plainly: to be the Python-based alternative to NetLogo, Repast or MASON. You define agents as Python classes, put them in a model, optionally place them on a grid or network, step the model forward and collect data as you go. Visualisation runs in the browser or in a Jupyter notebook through Solara.

The current stable line is Mesa 3, which needs Python 3.12 or newer, and the project has started work on Mesa 4 with pre-releases available. Mesa 3 is a real break from Mesa 2: the old scheduler classes and the unique_id argument on agents are gone, replaced by an AgentSet that the model manages for you. A lot of tutorials online still show the old API, so check the version before copying code.

Where it fits in AI-driven worlds

Mesa is the better choice when a simulation needs to be studied rather than just watched. Because the model is ordinary Python, the whole data ecosystem is available: pandas for the collected results, NumPy for anything numerical, NetworkX for social graphs, and plotting libraries for charts. That matters when you are tuning a game economy or checking whether an AI faction’s behaviour is balanced across hundreds of runs.

It also sits comfortably next to machine learning work. An agent’s step method can call a trained policy, a language model or any Python library, so Mesa works as a testbed for mixing hand-written rules with learned behaviour. You can prototype a market, an epidemic or a town of NPCs with goals, measure what happens, and only then port the parts that work into an engine.

For AI-assisted coding, Python is the language most assistants are strongest in, which lowers the cost of trying ideas. The usual caveat applies: assistants often produce Mesa 2 code, so you need to correct them towards the current API.

Strengths

• It is just Python. No new language to learn, and your model can import anything.
• Analysis built in. The DataCollector gathers model- and agent-level variables into pandas DataFrames, and batch runs let you sweep parameters.
• Spaces. Grids, continuous space and network spaces are included, with a newer cell-based discrete space module in Mesa 3.
• AgentSet. Selecting, filtering, shuffling and calling methods on groups of agents is concise, for example self.agents.shuffle_do("step").
• Browser visualisation. Solara-based components give you interactive dashboards with sliders without writing front-end code.
• Active, academic community. It has a peer-reviewed paper in the Journal of Open Source Software (2025), an examples library and regular releases.

Limits

• Speed. Pure Python loops over agents are slow compared with compiled or vectorised code. Tens of thousands of agents with complex rules will test your patience.
• API churn. The move from 2.x to 3.x broke a lot of existing code, and Mesa 4 is in development, so expect further change.
• Not a game runtime. There is no rendering engine, input handling or real-time loop suited to shipping a game. It is a research and prototyping tool.
• Dependencies are opt-in. From Mesa 3 the base install is minimal. In testing, a bare pip install mesa (version 3.5.1) failed on import because NetworkX was missing, so install the recommended extras.

Getting started

Install with the recommended extras into a Python 3.12+ environment:

pip install -U "mesa[rec]"

Here is the classic Boltzmann wealth model from the official tutorial, written against the Mesa 3 API. It was tested on Mesa 3.5.1 with warnings treated as errors:

import mesa

class MoneyAgent(mesa.Agent):
    def __init__(self, model):
        super().__init__(model)
        self.wealth = 1

    def exchange(self):
        if self.wealth > 0:
            other = self.random.choice(self.model.agents)
            other.wealth += 1
            self.wealth -= 1

class MoneyModel(mesa.Model):
    def __init__(self, n=100, rng=None):
        super().__init__(rng=rng)
        MoneyAgent.create_agents(model=self, n=n)

    def step(self):
        self.agents.shuffle_do("exchange")

model = MoneyModel(n=100, rng=42)
for _ in range(50):
    model.step()

print(sorted(a.wealth for a in model.agents)[-5:])

Note rng rather than seed: the seed keyword still works in 3.5 but raises a deprecation warning. From here, the official tutorials add a grid, data collection and a Solara dashboard step by step.

Verdict

Mesa is the sensible choice when you want an agent-based model you can interrogate with Python’s data tools, or plug into machine learning code. It is slower and less immediate than NetLogo, and the API has moved quickly, but for testing the systems behind an AI-driven world and measuring what they do, it is very good.