The OSMnx examples gallery is a notebook course on urban network analysis

A gallery of notebooks, and the library it demonstrates

The repository is a gallery of OSMnx tutorials, usage examples and feature demonstrations, and the primary language recorded for it is Jupyter Notebook.

The library being demonstrated is described in the Overview. OSMnx is a Python package to easily download, model, analyze, and visualize street networks and other geospatial features from OpenStreetMap. The readme puts the headline capability plainly: you can download and model walking, driving, or biking networks with a single line of code, then analyze and visualize them.

The rest of that sentence is the interesting part. The same package handles urban amenities and points of interest, building footprints, transit stops, elevation data, street orientations, speed and travel time, and routing. That is a wide surface for a single tool, and it is exactly the surface where a gallery of worked examples earns its keep, because the hard part of using OSMnx is not calling a function but knowing which function answers the question you have.

The examples live in a notebooks folder, and the readme says the gallery contains step-by-step usage tutorials and feature demonstrations as Jupyter notebooks. Step-by-step is the operative word, since a notebook that shows the call but not the reasoning around it does not teach much.

Run them in Colab or in the OSMnx image

There are two ways to run the notebooks, and the readme names both.

The first is interactively online with Colab, through the Open In Colab badge that runs the repository in Google Colab. The second is locally with the official OSMnx Docker image, which is published on Docker Hub under the gboeing/osmnx repository.

The Docker route is the more interesting one for an analyst who works with this data regularly, and the reason is in the dependency set rather than in the documentation. A notebook that draws street networks, plots interactive maps and computes network statistics needs a fairly large stack of geospatial and scientific libraries, and installing that stack is the part of getting started that most people would rather not do on their own machine. An image with the environment already assembled removes that step entirely, and removes the risk of a version mismatch making a notebook fail for a reason that has nothing to do with the example.

Colab covers the other case, which is a quick look or a demonstration to somebody else. The badge is at the top of the readme, so the path from the repository to a running notebook is one click.

For both routes, the readme is explicit about where the material lives. All of the examples are in the repository's notebooks folder.

Main branch tracks the library, tags track the releases

There is one versioning rule in the readme and it removes a whole category of confusion.

The main branch of the examples repository generally tracks the functionality of the OSMnx repository's main branch. For examples corresponding to previously released versions of OSMnx, you use the examples repository's tags to browse by release.

So there are two axes of versioning and the repository keeps them aligned. A developer working on OSMnx itself pushes changes to the library's main branch, and the examples follow, so the gallery always shows the current behaviour of the code. A user on a released version of OSMnx wants the gallery that was written for that release, and the tags give them that.

The tag list on the badge at the top of the readme is labelled Uses OSMnx, which is a good way to signal the connection between the two repositories without writing a paragraph about it.

The examples repository itself has no GitHub releases of its own, which is consistent with the role it plays. It is not a distributed artifact, it is a set of documents that are versioned in step with something else.

One pinned OSMnx version and an explicit extra for the examples

The project file is small and it tells you exactly what the notebooks need.

dependencies = ["osmnx[all]==2.1.1"]
requires-python = ">=3.11"

The OSMnx dependency is pinned to an exact version with the all extra, and the project version field is set to match that pinned version. The comment in the file says match pinned version above, which is the kind of note that exists because somebody once forgot and the CI caught it.

There is a second dependency group for the notebooks themselves.

examples = ["folium", "jupyterlab", "mapclassify", "igraph"]

Those four names are a summary of what the examples actually do. Folium is for the interactive web maps, JupyterLab is the notebook environment, mapclassify is for classifying values into classes, which is how a choropleth or a classified network map gets its colours, and igraph is the graph library that a network analysis example leans on.

The development group adds ipython, nbconvert, nbdime and prek. nbconvert is what turns a notebook into a document for publishing, and nbdime is what makes a diff of a notebook reviewable, which matters a lot in a repository whose entire content is notebooks. The ruff configuration follows, with a line length of 100, an extended rule selection, and a pycodestyle maximum set to 110 as a soft bound with the comment that it is the line length plus ten percent since it is not a hard upper bound.

The topic tags are a map of the field

The topic list on this repository is long and specific, and it is effectively an index of the subject area rather than of the software.

The tags are accessibility, binder, cities, city, jupyter-notebook, network-analysis, notebooks, openstreetmap, public-transport, python, street-networks, transit, transport, transportation, urban-analytics, urban-data-science, urban-design and urban-planning.

Three groupings are visible in that list. The technical ones describe the artifacts, street networks, network analysis, notebooks. The application ones describe the questions, accessibility, public transport, transit, transportation, urban analytics, urban data science, urban design and urban planning. And the platform ones are binder and jupyter-notebook.

That mix tells you what the gallery is actually for. A street network extracted from OpenStreetMap is an intermediate object, and the interesting work is what you ask of it. Is this neighbourhood walkable, and is that walkability accessible to a wheelchair user, is this transit stop connected to the amenities people need, and does the street orientation of a district tell you anything about its history. Those are the tags, and they are the reason an OSMnx tutorial is a research tutorial.

The cities and city tags suggest the other half of the audience, which is the urbanist or planner rather than the geospatial programmer, and a gallery that serves both is harder to write than one that serves either.

The citation is part of the package

The readme has a Citation section, and it is short.

If you use OSMnx in your work, please cite the paper. The reference is Boeing, G. (2025), Modeling and Analyzing Urban Networks and Amenities with OSMnx, in Geographical Analysis, volume 57, issue 4, pages 567 to 577, with the doi 10.1111/gean.70009.

A gallery of notebooks asking for a citation of a journal paper is doing something a repository of code usually does not, and the reason is that the output of this library is a research artefact. If a street network model ends up in a paper, the reader wants to know how it was built, and the paper is where that method is described.

The repository also carries the machine-readable form of that request, a CITATION.cff file at the top level, alongside a LICENSE.txt holding the MIT licence text, a CONTRIBUTING.md, a .pre-commit-config.yaml, a .python-version file and a uv.lock.

The uv.lock is worth a note for the same reason the pinned dependency is. A notebook that produces a map and a set of numbers is only reproducible if the versions of the libraries that drew them are fixed, and a lock file plus a pinned OSMnx version is the mechanism for that.

The readme closes with the three links a reader needs: the documentation, the journal article and the code repository of OSMnx itself.

What this repository is not

There are two limits worth stating, because both are easy to run into.

The first is scope. This is not OSMnx. The library lives in its own repository, and the examples repository contains notebooks, a project file and a lock file. If you want the package, you install it separately, and if you want to read its implementation, you go to the code repository linked at the bottom of the readme. The gallery is documentation that happens to be executable.

The second is version coupling. The examples are pinned to OSMnx 2.1.1, and the main branch of the examples tracks the main branch of the library rather than any released version. If you are working with a released version of OSMnx, the tags are what you want, and if you are reading the main branch you are reading behaviour that may not be in any release you can pip install.

There is also a practical limit that the readme does not advertise but the design implies. These notebooks talk to the OpenStreetMap data servers, so running them means making network requests to a public infrastructure, and the data behind a given example can change under you. That is a property of the data rather than of the gallery, and it is the reason the citation asks for the method rather than the artefact.

For an analyst learning the tool, the value of the gallery is that it shows the sequence, not just the call, and the pinning is what makes that sequence repeatable.

Editorial conclusion

Adopt this gallery as a course rather than as a dependency, and work through the notebooks before writing your own OSMnx code, because the demonstrations show the package doing the kind of work that is hard to guess from a function signature. Do not treat the repository as the library itself, since it contains no source code for OSMnx and only tracks the library's behaviour. Verify first that the pinned version of OSMnx in the project file matches the version you intend to use, and that you are on the branch rather than a tag if you want the newest behaviour, or on a tag if you want the examples that correspond to a released version.

Frequently asked questions

Official sources

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