Skip to main content
v2026.11,986 entries · CC-BY 4.0

UrbanSim: Land Use and Transport Simulation Platform

What UrbanSim is, how its estimate-then-simulate workflow runs, how it links to travel demand models, plus Python install steps and citations.

Written and maintained by CASRAI Editorial Board

Published

On this page

UrbanSim is an open-source simulation platform for modeling how cities and regions change over time: it forecasts real estate development, households and employment, and travel-related outcomes under alternative policy scenarios. Researchers and metropolitan planning organizations use it to compare long-range land use and transportation futures, and the current Python library from the Urban Data Science Toolkit (UDST) packages its estimation and simulation tools for reuse.

What is UrbanSim?

UrbanSim is a modular land use and transportation simulation system. Felsenstein, Axhausen and Waddell (2010) describe it in the Journal of Transport and Land Use as an open-source system built on highly disaggregated data and dynamic simulation, meaning it models individual households, firms, buildings and parcels year by year rather than relying on zone-level averages. The UDST documentation describes the present library as a platform for building statistical models of cities and regions, with tools for model estimation and simulation that forecast real estate development and demographics under policy scenarios.

The platform was designed by Paul Waddell, and Waddell (2002) in the Journal of the American Planning Association framed the original problem: the travel models that metropolitan planning organizations (MPOs) ran under federal mandates were not designed to link land use, transportation and the environment. UrbanSim was built to supply that missing land use side. For a broader grounding in the field it serves, see what urban planning is.

How does UrbanSim work? Estimate, then simulate each year

The UDST documentation states that an UrbanSim workflow is a series of models that are estimated and then simulated in sequence. Estimation fits statistical models to observed data, for example a hedonic price model that relates building or parcel prices to their characteristics. Simulation then applies the fitted models forward, one simulated year at a time, so the outputs of one year (new buildings, relocated households, changed prices) become the inputs of the next.

This is a microsimulation approach. It differs from a single closed-form equation: there is no one formula to report, and results emerge from many linked model steps. Planners therefore treat a run as a scenario, a consistent set of assumptions carried forward in time. Waddell, Boeing, Gardner and Porter (2018) call UrbanSim a strong scenario-analysis tool and describe its use by MPOs for forecasts that extend about 30 years. The library’s own examples include a hedonic price model, a San Francisco example, and a square foot pro forma and developer model for real estate development.

Land use change matters to transportation, and travel conditions matter back to land use, so the 2018 paper by Waddell and colleagues describes an integrated pipeline in which each stage hands results to the next. The data table below summarizes the roles of the stages it describes. It lists the land use model first, then an agent-based travel demand model, then traffic assignment, with congested travel times returning to the start. Agent-based travel demand models are a close relative of the approach explained in our agent-based model guide.

Two points are worth keeping apart when you describe this in a paper. First, UrbanSim itself covers the land use component; ActivitySim is a separate package for travel demand, and traffic assignment is a further stage. Second, the pipeline paper uses static user equilibrium assignment solved with the Frank-Wolfe algorithm, which is a choice made in that study rather than a requirement of UrbanSim.

Install UrbanSim and run a first Python model

The documentation checked on 2026-11-17 describes release 3.3, which requires Python 3.10 or later and is tested on Python 3.10 through 3.14. It installs with pip or conda, and NumPy, Pandas, Statsmodels and Orca are installed automatically as dependencies. The optional network utilities need Pandana and are installed through an extra.

pip install urbansim
conda install urbansim --channel conda-forge
pip install "urbansim[network]"

UrbanSim models are organized with Orca, a Python framework that registers named tables, columns, values and functions and injects them into functions by matching argument names. Tables are pandas DataFrames, and tables can come from databases, text files or shapefiles. Related tables are linked by index alignment: in the documentation’s example, the parcel_id field on buildings points to the parcels table. The pattern below is the documentation’s own example of registering tables and a computed column:

@orca.table('buildings')
def buildings(store):
    return store['buildings']

@orca.table('parcels')
def parcels(store):
    return store['parcels']

@orca.column('parcels', 'total_units')
def residential_unit_density(buildings, parcels):
    return buildings.residential_units.groupby(buildings.parcel_id).sum() / parcels.acres

In the Orca documentation, model steps are functions registered with @orca.step() and executed by orca.run(), which can repeat a sequence of steps over a range of years, as in orca.run(['print_year'], iter_vars=range(2010, 2015)). Steps are usually run for side effects such as updating tables, so their return values are discarded during a pipeline run. The yearly loop is the mechanism that turns a set of fitted models into a forecast. Because Orca stores columns separately from tables, a computed column such as total_units stays attached to its table even when the table is replaced.

Researchers who share such a workflow should also share the software environment; see sharing a reproducible conda environment.

The Orca building blocks, in plain terms

Orca gives UrbanSim projects a small vocabulary. The table below restates it from the Orca documentation so that a methods section can describe a model in the same terms the software uses.

Orca element What it is
Table A pandas DataFrame registered under a name, either with add_table() or by decorating a function with @orca.table().
Broadcast A defined relationship that lets tables be merged, for example buildings to parcels.
Column A Series or function registered on an existing table, so it can be computed from other data.
Injectable An arbitrary value or function registered by name and injected into other functions; with autocall=False the function itself is injected rather than its result.
Step A function registered with @orca.step() and run by orca.run(), usually for side effects such as updating tables.

When you write up a simulation, listing the tables, the computed columns and the ordered steps is a compact way to show a reader exactly what was run, and it makes the study easier for others to repeat.

How to read UrbanSim results

UrbanSim output is a set of simulated tables for each year, not a single statistic. The reading guidance below is editorial interpretation, drawn from how the cited papers describe the platform.

Output How to read it
Yearly tables of buildings, households or jobs One possible future under the stated scenario assumptions, not a forecast of what will certainly happen (Waddell et al. 2018 describe its strength as scenario analysis).
Differences between two scenarios The more defensible quantity, because shared assumptions affect both runs alike. Report what differs between scenarios and the policy lever changed.
Results after feedback from travel times Reflect the linked pipeline; state which models were coupled and how many iterations were run.

Assumptions, data needs and common mistakes

  • Data hunger. The system is built on highly disaggregated data, so a first project usually spends most of its effort assembling parcel, building, household and job tables (Felsenstein et al. 2010).
  • Transferability. Felsenstein and colleagues note that UrbanSim was developed in the United States and that European applications need adaptation. Do not assume that a model specification estimated in one region transfers to another.
  • Confusing the platform with its parts. Land use simulation, travel demand and traffic assignment are separate components in the integrated pipeline; attribute results to the right one.
  • Mixing up the library and the company. The open-source Python library is distributed by UDST, while UrbanSim Inc. is a separate organization named in the library’s copyright notice. The documentation checked here does not state a license, so check the repository before reusing code.
  • Reporting one run as the answer. Because simulations are scenarios, document the inputs, random settings if any, software version and the scenarios compared.

How to cite UrbanSim

Cite the study papers for the method and the software documentation for the version you ran. Two journal references from the sources below, in APA 7th style, are:

Felsenstein, D., Axhausen, K. W., & Waddell, P. (2010). Land use-transportation modeling with UrbanSim: Experiences and progress. Journal of Transport and Land Use, 3(2). https://doi.org/10.5198/jtlu.v3i2.183

Waddell, P., Boeing, G., Gardner, M., & Porter, E. (2018). An integrated pipeline architecture for modeling urban land use, travel demand, and traffic assignment. arXiv. https://arxiv.org/abs/1802.09335

State the UrbanSim version number you used in the methods text, and name any companion packages such as ActivitySim and Orca.

Sources

Data: Stages of the UrbanSim integrated land use, travel demand and traffic assignment pipeline

Compiled by CASRAI from Waddell, Boeing, Gardner and Porter (2018) and the UDST UrbanSim documentation. Each row names a pipeline stage, what it models and how it connects to the next stage in the integrated architecture.

Stages of the UrbanSim integrated land use, travel demand and traffic assignment pipeline
StageWhat it modelsLink to the next stage
UrbanSimLand use microsimulation: real estate development and demographics under policy scenariosProvides land use inputs to the travel demand model
ActivitySimAgent-based travel demand, producing synthetic origin-destination tripsProvides trips to traffic assignment
Traffic assignmentStatic user equilibrium assignment solved with the Frank-Wolfe algorithmProduces congested travel times
FeedbackCongested travel times returned to the modelsUsed by UrbanSim and ActivitySim in the next run

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about UrbanSim: Land Use and Transport Simulation Platform

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →