OSMnx: turning OpenStreetMap into a graph you can actually analyze

A package whose README is mostly links

OSMnx describes itself in one sentence: a Python package to download, model, analyze and visualize street networks and other geospatial features from OpenStreetMap. Everything else on the README page is a link, and that is not laziness. The project has separated the short pitch from the long documentation with some discipline.

The structure of the page tells you what the project considers important in order. There is a PyPI version badge and a downloads badge, then documentation, build and coverage status badges, then the description, then a citation request. After that come Getting Started, Installation, Support and License, each of which is a paragraph pointing somewhere else.

The citation request is the most unusual thing on the page. OSMnx asks that any use in published work cite a specific paper: Boeing, G. (2025), Modeling and Analyzing Urban Networks and Amenities with OSMnx, in Geographical Analysis, volume 57 issue 4, pages 567 to 577. A `CITATION.cff` file in the repository root means the correct citation can be produced automatically rather than typed by hand. For a package used in urban research, that is a reasonable expectation rather than an unusual one, and it tells you something about who the audience is.

The dependency list explains the design

The core dependency set is short and every entry is a well-known scientific Python package:

dependencies = [
  "geopandas>=1.0.1",
  "networkx>=2.5",
  "numpy>=1.24",
  "pandas>=1.5",
  "requests>=2.30",
  "shapely>=2.0",
]

Read it as an architecture summary. Shapely handles geometry, geopandas gives you the tabular and spatial data frame, networkx is the graph representation, and pandas plus numpy do the arithmetic. OSMnx itself is not implementing any of those layers, which is why it can present a street network as something you compute statistics on directly instead of writing your own graph traversal.

The minimum floors are worth noting. geopandas 1.0.1, shapely 2.0 and networkx 2.5 are recent floors rather than permissive ones, so an older scientific stack in your environment is a likely cause of install trouble. `requests` at 2.30 is the only HTTP dependency, which tells you the package is making its own calls to Overpass and Nominatim rather than wrapping a larger geospatial client.

Everything beyond that core is optional, and the extras are grouped by capability:

[project.optional-dependencies]
all = ["osmnx[entropy,neighbors,raster,visualization]"]
entropy = ["scipy>=1.10"]
neighbors = ["scikit-learn>=1.2", "scipy>=1.10"]
raster = ["rasterio>=1.4", "rio-vrt>=0.3"]
visualization = ["matplotlib>=3.6"]

So you pay for raster processing only if you touch elevation data, for scikit-learn only if you do neighbor analysis, and for matplotlib only if you plot. The single `all` extra exists for people who want everything, which is a thoughtful default for a package that otherwise punishes nobody.

Version 2.1.1 on Python 3.11 and newer

The build configuration is explicit about what it supports:

version = "2.1.1"
requires-python = ">=3.11"
build-backend = "uv_build"

The classifiers agree with the constraint, listing Python 3.11, 3.12, 3.13 and 3.14 alongside the Python 3 only marker, and the project is classified as Production/Stable for development status. The floor is called out in the file itself with an inline comment explaining it matches both the classifiers and the type checker version, so the constraint is deliberate rather than an accident of a version bump.

The build backend is `uv_build`, pinned as a build requirement in the same file, which tells you the packaging has moved to the newer uv-based build path rather than the older setuptools one. The project is also marked `Typing :: Typed`, so inline type information is shipped rather than left to a separate stub file.

Version 2.1.1 is a mature 2.x line rather than a fresh major. That matters for anyone arriving from an older 1.x tutorial, where the configuration model and some function signatures changed. The repository keeps a `CHANGELOG.md`, which is where a migration question gets settled. The repository is not archived and the last push was on 2026-07-31, with 5853 stars and 893 forks.

What the package claims it can work with

The README makes two claims worth separating, because they have different difficulty levels.

The first is networks. You can download and model walking, driving or biking networks with a single line of code, then analyze and visualize them. That is the core competency and the reason the package exists. The second claim is breadth: urban amenities and points of interest, building footprints, transit stops, elevation data, street orientations, speed and travel time, and routing. These are all OpenStreetMap feature types that need different handling, and the fact that one package covers them is a genuine convenience rather than a marketing line.

The repository topics confirm the intended audience: twenty tags spanning geospatial analysis, urban planning, transportation, networks, routing and OpenStreetMap itself. `networkx` is listed as a topic as well, which fits the dependency set.

What the README does not do is show you any of this working. There is not a single code block on the page. The reason is that the examples live in a separate repository, `gboeing/osmnx-examples`, described as a gallery of step-by-step tutorials and sample code. That is a deliberate split: the package repository stays reviewable, and the tutorials get a home that can be updated without touching release history.

Licensing has two halves and the second one is your problem

OSMnx is MIT licensed, which the README states plainly. The next sentence is the part that catches people out: OpenStreetMap's own open data license requires that derivative works provide proper attribution.

That means two obligations sit on top of each other. Your code's license is yours, and the data you downloaded carries its own attribution requirement that survives into anything you publish from it. The README points to the Getting Started guide for usage limitations, which is where those limits are described.

This is the single most common surprise for people new to OpenStreetMap tooling. The failure mode is a paper, report or dashboard with a map in it and no credit line, which is a licensing problem rather than a technical one, and it is discovered late. If your output is going anywhere public, resolve the attribution question before you start rather than after the analysis is finished.

The MIT license file itself is `LICENSE.txt` in the repository root, and third-party licensing information is not something this project has to spell out in the way a vendored-code project would.

Where to actually start, since the repository will not tell you

The support section sets expectations in a useful way. The repository is hosted on GitHub, but the README asks that how-to and usage questions go to StackOverflow with an OSMnx tag, explicitly reserving the issue tracker for bug tracking and feature development. That is a healthy division, and it also means searching an existing question is likely to be faster than opening an issue.

The documentation site, osmnx.readthedocs.io, is the project's real manual. The Getting Started guide there is described as an introduction to the package plus a FAQ, the User Reference is where the API is documented, and the Installation guide is where you get the install command. None of that is duplicated in the repository, so you will need the site open alongside your editor.

The repository tree explains the layout. The package itself is under `osmnx/`, documentation sources under `docs/`, tests under `tests/`, environment definitions under `environments/`, and there is a `CONTRIBUTING.md` and a `.pre-commit-config.yaml` for anyone preparing a patch. The version is also a 2.x line, so if you find an older tutorial using a different configuration approach, treat the changelog as the authority.

A sensible order is: install from the documentation, download one city as a walking network from the examples gallery, compute something small on it, then read the user reference for the analysis functions. That gets you to a working mental model in under an hour without reading the source.

Editorial conclusion

OSMnx is the shortest route from a place name to a graph you can compute on, and its dependency list is the reason that works: geopandas, shapely, networkx, pandas and numpy rather than a bespoke geometry engine. The version pinned in `pyproject.toml` is 2.1.1, requiring Python 3.11 or newer, and optional extras pull in rasterio, scikit-learn, scipy or matplotlib only when you need them. What the repository does not give you is any of the how-to material: a single install command, a worked example, an API reference. All of that lives on osmnx.readthedocs.io and in the separate osmnx-examples gallery. Install from that guide, then build your first network there rather than guessing at parameter names, and read the usage limitations before publishing anything derived from OpenStreetMap data.

Frequently asked questions

Official sources

1. gboeing/osmnx on GitHub
2. Issues
3. License: MIT
4. Project website
5. README