# Eclipse SUMO: A Microscopic Traffic Simulator You Build Yourself

> Eclipse SUMO is an open source, highly portable, microscopic and continuous traffic simulation package built for large road networks and intermodal scenarios. Its strength is scale and tooling; its cost is a CMake build and a documentation set that tracks the development branch.

**eclipse-sumo/sumo** — Eclipse SUMO is an open source, highly portable, microscopic and continuous traffic simulation package designed to handle large networks. It allows for intermodal simulation including pedestrians and comes with a large set of tools for scenario creation.

- Repository: https://github.com/eclipse-sumo/sumo
- Website: https://eclipse.dev/sumo
- Stars: 4,197 · Forks: 1,760
- Language: Python
- License: EPL-2.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/eclipse-sumo-sumo

## What Eclipse SUMO Does That a Macroscopic Model Cannot

Eclipse SUMO stands for Simulation of Urban MObility. The README describes it as an open source, highly portable, microscopic and continuous traffic simulation package designed to handle large road networks and different modes of transport, including pedestrians. Those adjectives are the whole pitch. Microscopic means individual vehicles are simulated rather than aggregate flows, so intersection behaviour, lane changing and queue spillback emerge from the model instead of being averaged away. Continuous means time advances in small steps rather than in fixed intervals. The target user is not someone sizing a highway lane count. It is a researcher, a traffic engineer or a planning team that needs to ask what happens at the level of individual vehicles and travellers, on a network big enough that the answer is not obvious.

The README also states that the project is mainly developed by employees of the Institute of Transportation Systems at the German Aerospace Center. That matters for how you read the documentation: this is a research-grade simulator with a long institutional backing, not a commercial product with a support contract. The repository layout reflects that. Alongside src/ and tests/ there are tools/, data/, docs/ and examples directories, so scenario creation is treated as part of the package rather than something you buy separately.

## How the Simulation Is Organised: Networks, Routes and Config Files

The README points new users at the docs/tutorial and examples directories, which it says contain example networks with routing data and configuration files. That sentence describes the core data flow of the whole system. You do not start the simulator and draw roads in a GUI. You assemble input files: a network describing the road geometry, routing data describing demand, and a configuration file that ties them together and sets simulation options. The simulator then reads that configuration and produces output.

The top-level repository entries confirm the split between engine and tooling. src/ holds the simulation core, while tools/ holds the scenario creation utilities the README mentions in the project description. The bin/ directory is what ends up on your path. Because the primary language field for the repository is Python while the simulator core is compiled, expect a mixed workflow: a compiled binary doing the time-stepping, and Python tooling around it for preparing inputs and post-processing outputs. The documentation lives in docs/, with an offline copy shipped inside every release that the README says is accessible at docs/userdoc/index.html. That offline copy is the one you should trust when you are working without network access, because the online manual is explicitly tied to the development version.

## Installing Eclipse SUMO and Running a First Scenario

The README gives a downloads site as the primary distribution channel and then advises using the latest sources from GitHub, since the program is still under development and is being extended continuously. The clone is recursive because the build pulls in submodules.

```bash
git clone --recursive https://github.com/eclipse-sumo/sumo
```

On Windows the README says pre-compiled binaries and CMake files for generating Visual Studio projects are provided, and that developers should also clone the dependent libraries from the SUMOLibraries repository.

```bash
git clone --recursive https://github.com/DLR-TS/SUMOLibraries
```

On Linux the README first suggests checking whether your distribution already packages sumo, and mentions a PPA for Ubuntu users and an open build service instance. If you build it yourself, the documented Ubuntu steps set SUMO_HOME to the checkout, install the dependency lists shipped in build_config, then configure and build with CMake.

```bash
cd <SUMO_DIR>
export SUMO_HOME="$PWD"
sudo apt-get install $(cat build_config/build_req_deb.txt build_config/tools_req_deb.txt)
cmake -B build .
cmake --build build -j$(nproc)
```

The README does not document a rollback or uninstall procedure, and it does not list a version number for the dependency files, so treat the contents of build_config as the authoritative dependency set for the revision you cloned. After the build, the README's getting-started instruction is to look in docs/tutorial and examples for example networks with routing data and configuration files. Start there rather than writing a network from scratch: those examples are the only worked scenario the repository itself points you to.

## The Documentation Tracks Development, Not Your Binary

The most important practical limitation is stated plainly in the README's documentation section. The main documentation at sumo.dlr.de/docs tracks the development version, and the README links to an FAQ entry asking why SUMO does not behave as documented in the wiki. A mirror exists at eclipse.dev/sumo/docs/, and an offline copy ships with every release at docs/userdoc/index.html. If you install a distribution package or a tagged release and then follow the online manual, you can hit behaviour that has already changed. The offline copy inside your release is the safer reference, and the README's own advice to use the latest sources is consistent with that: the project would rather you run development code than run stale code against current docs.

A second limitation is the build itself. There are pre-compiled Windows binaries, but the Linux path the README documents is a source build with CMake and two apt dependency lists. That is a reasonable ask for a research group and a poor fit for a team that wants a container image and a version pin. The README also does not describe a supported upgrade path between versions, so version-to-version migration is something you verify against the ChangeLog file at the repository root rather than against a documented procedure.

## Where Eclipse SUMO Is the Wrong Tool

If your question is about corridor-level capacity, travel demand forecasting over decades, or emissions accounting at regional scale, microscopic simulation is the wrong instrument. Simulating individual vehicles to answer an aggregate planning question costs orders of magnitude more compute and introduces calibration burden that a macroscopic assignment model does not have. The README's own framing, large road networks and different modes of transport, points at studies where the interaction between vehicles and modes is the object of interest.

It is also the wrong tool if you cannot own a build. A team without anyone comfortable with CMake, C++ toolchains and Python tooling around a compiled binary will spend its first weeks on the toolchain rather than on traffic. The README's Linux instructions are explicit about apt, CMake and environment variables, and the Windows instructions explicitly require cloning a separate libraries repository for development. There is no documented single-command install that covers every platform. Finally, if you need guaranteed API stability across upgrades, the README's own admission that the program is still under development and that the online manual follows development is a warning, not a formality.

## Eclipse SUMO Compared with MATSim and Commercial Microsimulators

The closest open source alternative in spirit is MATSim, which takes a different approach: it is activity-based and iterative, assigning a synthetic population of agents to a network and letting each agent replan across iterations until the demand settles. Eclipse SUMO, by contrast, is a traffic flow simulator. Its unit of interest is the vehicle and its movement through a network in continuous time, with pedestrians and other modes included in the same run. If your question is how a population's daily schedule responds to a policy, MATSim's iteration loop is the natural fit. If your question is what happens at a specific junction when demand rises, Eclipse SUMO is.

Commercial microsimulators occupy the same conceptual ground as Eclipse SUMO and differ mainly in what surrounds the engine: vendor support, GUI-centred scenario editing, and a manual frozen to the shipped version. Eclipse SUMO's trade is the reverse. You get the source, the tools/ directory, and a documentation set that follows development, and you take on the build and the version discipline yourself. The EPL-2.0 licence is the other difference worth noting: it is a weak copyleft licence, so if you modify and redistribute SUMO itself you carry obligations, while the README points to a Libraries_Licenses documentation page for the licences of bundled libraries and supplementary code. This is a description of the terms, not legal advice; check the actual licence text before you redistribute anything.

## Maintenance Signals and What They Mean for Adoption

The repository is not archived, and the last push was on 2026-09-23. The README states that the program is still under development and is being extended continuously, and the presence of CI workflows for Windows, Linux and macOS in the badge list is consistent with that. The repository also carries a ChangeLog, a CITATION.cff, contribution guidelines and a code of conduct, which is the file set of a project that expects outside contributions rather than one maintained behind a wall.

For upgrade cost, the practical constraint is the documentation mismatch described earlier. Because the online manual follows development, the reliable way to know what changed between the version you run and the version you are moving to is the ChangeLog at the repository root, plus the offline docs/userdoc/index.html shipped inside the target release. The README does not describe a supported migration path or a deprecation policy, so plan upgrades as a rebuild plus a re-read of the change log rather than as a package manager operation. Contact channels are the sumo-user and sumo-announce mailing lists, both requiring a subscription for the sending address, and the GitHub issue tracker for bugs and requests. The README asks that bug reports first be checked against a current checkout or a nightly build.

## Conclusion

Adopt Eclipse SUMO if you need microscopic simulation of large road networks with pedestrians and other modes, you are willing to build from source with CMake, and you can read C++-era documentation that explicitly tracks the development version. Do not adopt it if you need a hosted service, a one-click installer for every platform, or a stable frozen manual that matches your binary exactly. Before committing, verify three things on your own machine: that your distribution package or the PPA gives you a SUMO version recent enough for your scenario, that the tools/ directory contains the scenario-creation utilities your pipeline needs, and that your team accepts EPL-2.0 obligations for any code you redistribute.

## FAQ

### What does Eclipse SUMO software do?

It is a microscopic and continuous traffic simulation package that handles large road networks and different modes of transport, including pedestrians, and it ships with tools for scenario creation. It is mainly developed by the Institute of Transportation Systems at the German Aerospace Center.

### What is Simulation of Urban MObility?

It is the full name behind the acronym SUMO, used by Eclipse SUMO. The README describes it as an open source, highly portable, microscopic and continuous traffic simulation package.

### How do I install Eclipse SUMO on Linux?

The README suggests first checking whether your distribution already packages sumo, and mentions a PPA for Ubuntu and an open build service instance. To build from source it documents setting SUMO_HOME, installing the dependency lists in build_config, then running cmake -B build . and cmake --build build -j$(nproc).

### Where do I find Eclipse SUMO tutorial material and examples?

The README points to the docs/tutorial and examples directories, which it says contain example networks with routing data and configuration files. An offline copy of the documentation is part of every release and can be accessed via docs/userdoc/index.html.

### Does the Eclipse SUMO documentation match the version I installed?

Not necessarily. The README states that the main documentation tracks the development version, and it links to an FAQ entry about SUMO not behaving as documented in the wiki. The offline copy shipped inside your release is the version-matched reference.

## Sources

- [eclipse-sumo/sumo on GitHub](https://github.com/eclipse-sumo/sumo)
- [Issues](https://github.com/eclipse-sumo/sumo/issues)
- [License: EPL-2.0](https://github.com/eclipse-sumo/sumo/blob/main/LICENSE)
- [Project website](https://eclipse.dev/sumo)
- [README](https://github.com/eclipse-sumo/sumo/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/eclipse-sumo-sumo