UrbanSim: building statistical models of cities under policy scenarios

What UrbanSim models and who uses it

UrbanSim is a platform for building statistical models of cities and regions. The models help forecast long-range patterns in real estate development, demographics and related outcomes under various policy scenarios.

That framing is important, because this is not a data analysis library and not a forecasting API. It is a set of components for constructing agent-based models of urban systems, where households, employers and buildings make choices that aggregate into a regional outcome. The README describes the mission as providing methods and reusable model components for building self-managed simulations of urban development, household and employment location, real estate markets and related regional change.

The project lists what it maintains: statistical model components used in urban simulation, location-choice, relocation, transition and development models, real-estate feasibility and related urban-development methods, estimation and simulation utilities, model APIs and configuration patterns, and reusable components for assembling regional implementations.

The user base is stated plainly. UrbanSim models are used by public agencies, consultancies and researchers in dozens of cities around the U.S. and the world. The intended audience in the package metadata is Science/Research.

The `urbansim` Python library is the core component, containing tools for statistical estimation and simulation, the domain logic about housing markets and household relocation, and the frameworks and utilities for assembling a model. The scope is deliberately a library and not an application, which means you assemble the model yourself.

One structural detail worth flagging: the README states that the project status is Active, and that changes to the project's mission or execution architecture are considered through UDST's organization-level governance process. So the direction of the platform is not decided by pull requests alone.

urbansim is one library inside the UDST toolkit

The README is unusually clear that a full UrbanSim model needs more than this package. Operational models begin with detailed data about a particular region, then estimate and validate a system of interconnected model components, and full models draw on a number of libraries.

The named companions are Orca for task orchestration, Synthpop for population synthesis, and Pandana for network analysis, and the README collects these and the others into the Urban Data Science Toolkit, UDST. The San Francisco example implementation is linked as a concrete example of how the pieces fit together.

UrbanSim is designed to work with other UDST libraries and with external data, estimation, accessibility and workflow systems through documented Python interfaces and model specifications. That phrase, documented Python interfaces and model specifications, is the integration contract, and it matters for a team choosing components.

The project also describes its architecture as portable and self-managed, designed primarily for conventional CPU-based execution, and says that the reusable model components and interfaces can also be implemented by other execution engines. In other words, the components are meant to be portable out of the default engine rather than welded to it.

The commercial dimension is stated openly. The core platform is open source, but many operational models make use of additional cloud-hosted model building and visualization tools provided by UrbanSim Inc., with documentation for the cloud platform called UrbanCanvas hosted separately. The repository also links UDST's own project directory and its page on open-source projects and commercial offerings, which is a good sign that the boundary is documented rather than discovered.

Installing with pip or conda, and the optional network extra

UrbanSim requires Python 3.10 or later, and the package metadata confirms this with `requires-python = ">=3.10"` and classifiers for Python 3.10 through 3.14.

The two installation routes are given in the README:

* ``pip install urbansim``
* ``conda install urbansim --channel conda-forge``

There is also an optional extra for the network accessibility utilities, which require Pandana. The README gives it as `pip install "urbansim[network]"`, and the packaging metadata agrees, with a `network` optional dependency group holding `pandana>=0.8`.

That optionality is worth understanding before you install. Pandana is the library that does fast network accessibility analysis, so if your model depends on travel times to jobs and amenities, you need the extra. If your model does not touch accessibility, leaving it out keeps your environment smaller.

The runtime dependency set is visible in the metadata and explains what the library is built on:

dependencies = [
    "numpy>=1.26",
    "orca>=1.8",
    "pandas>=2.2,<4",
    "patsy>=0.5.6",
    "prettytable>=3.10",
    "pyyaml>=6.0",
    "scipy>=1.10",
    "statsmodels>=0.14",
    "toolz>=0.12",
]

`numpy`, `pandas` and `scipy` are the expected numeric stack, `statsmodels` is what supplies the estimation and regression machinery, `patsy` supplies the formula language used to specify models, `pyyaml` carries model configuration, `prettytable` handles tabular reporting, `toolz` provides functional helpers, and `orca` is the task orchestrator. The version floors are worth noting, since `pandas>=2.2,<4` and `numpy>=1.26` are recent enough that an older scientific environment will need upgrading first.

Estimation, simulation and the configuration pattern

The library's contents divide into two activities that the README names explicitly: statistical estimation and simulation. Estimation turns a set of observed choices into fitted model parameters, and simulation then runs those parameters forward to produce outcomes under a scenario.

The domain models listed in the project scope are the substance: location-choice, relocation, transition and development models, plus real-estate feasibility methods. The vocabulary is a vocabulary of urban modelling rather than of general data science. A location-choice model assigns households to places given attributes and alternatives, a relocation model decides who moves, a development model decides what gets built, and real-estate feasibility decides which developments are possible given a price or density constraint. A model that a city wants to run against a new zoning policy or a new transit line is assembled from those parts.

Configuration is handled through model APIs and configuration patterns, and the presence of `pyyaml` among the dependencies plus YAML configuration in the documentation indicates that model parameters and settings are expressed as data rather than code. That is a good design for a model you need to re-run with different inputs, and it is also what makes a model reviewable by a planner who does not write Python.

The estimation and simulation utilities, plus the data structures they operate on, are the reusable surface. The repository layout supports this reading: a `urbansim/` package, a `docs/` directory, `requirements-min.txt` alongside `requirements-dev.txt`, and a `CHANGELOG.rst` for tracking behaviour changes across versions.

Version history, the 3.2 to 3.3 gap and the upgrade question

The release history has a shape that tells you something. Version 3.2 was tagged on 2020-05-15, then 3.3rc1 on 2026-09-16, and 3.3 on 2026-09-16, with the last push to the default branch on 2026-10-12.

That is a six-year gap between tags, followed by a release candidate and a final release on the same day. Read one way, it is a long period of development that produced a large batch of changes, culminating in a 3.3 release. Read another way, it is a project whose tagging has been irregular. Either way, the practical question for an adopter is the same: the jump from 3.2 to 3.3 is where any breaking change lives, and the `CHANGELOG.rst` file in the repository is where you find out what changed.

The version number itself is not written in the packaging metadata, which declares a dynamic version read from `urbansim.__version__`. The version is therefore a property of the source tree rather than of the build configuration, which is a common setup and also means an installed copy reports the version of the code it was built from.

The dependency constraints are the other upgrade concern. The upper bound on `pandas` is `<4` and there is no upper bound on `numpy`, `scipy` or `statsmodels` beyond their floors, so a future major release of one of those packages could interact badly with an older UrbanSim. If you are pinning an UrbanSim version for a production planning workflow, pinning the numeric stack around it is the safer habit.

The licence, the governance and the honest limits

UrbanSim is licensed BSD-3-Clause, and the metadata records it alongside a `LICENSE.txt` file in the repository. The author entry in the metadata is UrbanSim Inc., which is worth noticing in combination with the governance note. The library is BSD licensed, the package is published by a company that also sells cloud tooling, and changes to the mission or execution architecture go through UDST's organisation-level process. A permissive licence plus a corporate steward plus a governance process is a specific arrangement, and it is documented rather than hidden.

The first real limit is the data. The README says operational models begin with detailed data about a particular region, and there is no way around that. UrbanSim is not a tool that turns a census extract into a forecast, and the modelling effort sits in the estimation and validation, not in the call to a function.

The second is the environment. The numeric stack is modern and fairly wide, the toolkit around it is large, and the project documentation points to separate pages for the toolkit libraries and the cloud platform. Assembling a working environment for a new user is a project in itself, and the README does not describe a single command that produces a runnable model.

The third is scope. The library covers urban development, household and employment location, and real estate markets. It says nothing about transport demand modelling, land use regulation modelling or macroeconomic forecasting, so a question that crosses into those areas is not answered here.

A final caution about the alternatives. The related toolkit libraries, Orca, Synthpop and Pandana, are described at a high level in the README, and the same organisation maintains them, so a comparison of approaches has to be made at the level of role rather than feature. The real difference is that UrbanSim is the model layer, Orca is the process layer that runs model steps, Synthpop produces the synthetic population that agents draw from, and Pandana computes network accessibility. A team that only needs fast travel-time queries for a dashboard has no reason to adopt UrbanSim at all.

Editorial conclusion

Adopt UrbanSim when you are building a real urban model with regional data, when you need household relocation, location choice, real estate feasibility and development components that you can estimate and then run under alternative policy scenarios, and when you are prepared to assemble the surrounding toolkit. Do not adopt it for a small descriptive question about a city's growth, because the cost is in the data and the calibration rather than the API. Before you start, confirm the model inputs you have, since operational models begin with detailed data about a particular region, check that Python 3.10 or later is available to you, and decide early whether you will also need Orca for orchestration, Synthpop for population synthesis and Pandana for network analysis.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. README
4. Releases
5. UDST/urbansim on GitHub