OSMnx 2.0 Migration Guide

[gboeing]

Overview

OSMnx 2.0.0 is targeted for release later in 2024. This major release includes some breaking changes (including removing previously deprecated functionality) that are not backwards compatible with v1. This issue provides guidance on migrating from v1 to v2. It will be updated as more details are finalized.

Beta testers needed

Testers needed! OSMnx 2.0.0 is now in beta. You can help test it by installing the latest pre-release. Create a virtual environment then run pip install --pre osmnx

Migrating to v2

The easiest way to ensure your code is fully compatible with OSMnx v2 is to install the latest v1 release (currently 1.9.4), then run your code. The latest v1 release will remain compatible with the v1 API, but any deprecated functionality you're using will issue a FutureWarning with simple guidance to make it v2 compatible. Additionally, you can:

• try out the latest 2.0.0 beta pre-release as described above.
• refer to the new official OSMnx reference paper up-to-date for v2
• check out the Examples Gallery, which has been updated for v2 compatibility if you're looking for sample code
• see the changelog for details

Key changes

The three biggest overarching changes in 2.0 are:

1. The package is now fully type-annotated throughout.
2. Several modules have been refactored or wholly rewritten for performance optimization.
3. The package's API has been streamlined and made more consistent, including some breaking changes and some moved/renamed functions.

In addition to these, there have been many smaller enhancements, fixes, and changes. See the changelog for details and see the latest documentation for an up-to-date user reference.

[gboeing]

The first OSMnx v2.0.0 pre-release (beta0) has been released. Testers needed!

[EwoutH]

Briefly tested beta0 on a few of my existing notebooks. No major issues so far!

[jGaboardi]

I'm also seeing no major/unexpected issues thus far.

[csebastiao]

No issues observed on a couple of my typical use cases !

Noting there in case the FutureWarning coming from Geopandas in the 1.0.0 latest version when calling geopandas.GeoSeries.unary_union(), in osmnx.graph.graph_from_place(), or osmnx.plot.plot_figure_ground() for instance.

[gboeing]

Thanks @csebastiao. I'll make sure to resolve that FutureWarning before the next 2.0 beta release. I'm also planning to release a final patch version of 1.x at some point with pinned max dependency versions to avoid future dependency deprecation issues.

[EwoutH]

For me, the testing timeline doesn't need to be this long. I'm fine with two betas a few weeks apart and then one or two release candidates.

A new, stable version of osmnx before the academic year starts also has it's advantages.

Of course I understand there might be other interest or constraints at play, but I wanted to share my perspective.

[gboeing]

@EwoutH thanks. I'm specifically avoiding releasing breaking changes before the semester. Given OSMnx's use in academia, I have learned that many users won't even see the deprecation warnings from v1.9.x unless we give them a semester with it. Ideally their update cycle will expose them to those warnings this fall so they can update their code before 2.0 appears just after the semester.

Beta 1 should arrive within the next two weeks. And prior to the official release of 2.0, users can always pip install the beta to get the latest enhancements.

[EwoutH]

Can we add a Breaking changes section somewhere (here or in the changelog)? To make things like changing the bounds order stand our a little more.

[EwoutH]

This code, which worked on OSMnx 1.x:

road_network = ox.load_graphml("merged_network.graphml")

city_name = "Rotterdam"
surrounding_area_name = "South Holland"
color_map = {city_name: 'red', surrounding_area_name: 'blue'}

edge_colors = [color_map[road_network.edges[edge]['network']] for edge in road_network.edges]

Now breaks on 2.0.

TypeError                                 Traceback (most recent call last)
Cell In[13], line 3
----> 3 edge_colors = [color_map[road_network.edges[edge]['network']] for edge in road_network.edges]

TypeError: unhashable type: 'list'

Has anything changed in the edge view?

[EwoutH]

Sorry, it looks like this isn't a OSMnx, since the same error appear when using OSMnx 1.9.3.

Did anything change in GeoPandas, NetworkX or an other dependency?

[gboeing]

Did anything change in GeoPandas, NetworkX or an other dependency?

I can't guess because I can't reproduce your error. However, if it is a dependency issue for OSMnx, it'll be resolved on the OSMnx side in the 1.9.4 release as we have pinned max dependency versions.

[EwoutH]

Yeah I think it was something on my side. If I encounter it again I will create a minimal reproducible example.

[Robinlovelace]

As per the above commit, we're trying to install a version of osmnx that is compatible with the latest version of geopandas but to no avail currently.

Error message:

The conflict is caused by:
    The user requested geopandas>=1.0.0-alpha1
    osmnx 1.9.4 depends on geopandas<0.15 and >=0.12

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

As far as I can tell from the conversation above, it should be compatible with geopandas 1.0.0 but will check... Any ideas welcome, see here for details: geocompx/geocompy#241

[Robinlovelace]

OK, seems it's an issue with installing the latest version of osmnx

osmnx/osmnx/_version.py

Line 3 in 8df6d7a

__version__ = "2.0.0b1"

[Robinlovelace]

Have tried to install the latest version with

pip install --pre osmnx

but that seems to get v1.9.4, right?

[Robinlovelace]

but that seems to get v1.9.4, right?

Update: no, after testing with the following reproducible example:

docker run -it python /bin/bash
root@77d9f959ad9d:/# pip install --pre osmnx
root@77d9f959ad9d:/# python
>>> import osmnx
>>> print(osmnx.__version__)
2.0.0b1

[Robinlovelace]

Will try with:

pip install --no-cache-dir --upgrade --pre osmnx

[Robinlovelace]

Source: https://stackoverflow.com/a/44008863

[gboeing]

I would expect #1123 (comment) to work.

[Robinlovelace]

Yes it did, although that was being overridden in our workflow. Fixed longer term (in a way that will keep updating to the latest versions) with the following command before running pip install -U --upgrade-strategy eager -r requirements.txt, sharing below in case of use/interest to others:

pur -r requirements.txt --pre osmnx

Source: geocompx/geocompy@30ffd68

[Robinlovelace]

By the way, as a relative Python novice, I'm interested in best practice and would welcome any suggestions on how to improve our set-up/installation/CI game.

[jamongadejoa28]

Numpy's latest version of 2.1.0rc1 and osmnx's 2.0.0b1 are incompatible. When converting osm data, when I look at the log history, when the tool invokes the coordinate values, it prepends a number with float64. If you look at the 2.0.0 version release of numpy, you can see that float_ has been deleted and replaced by float64. Please let me know the most stable versions of numpy and other tools that are compatible.

[gboeing]

@jamongadejoa28 OSMnx 2.0 should be fully compatible with Numpy 2.0. If you discover a specific incompatibility, please open a new issue with complete troubleshooting details so we can resolve it.

[EwoutH]

I'm now changing the order of the coordinates in public examples. It's a bit weird to need to stay on a beta release for almost half a year. Maybe I'm too early, but I would support going a lot faster with the 2.0 release schedule.

Even huge projects as NumPy or Pandas have way shorter pre-release periods.

Maybe something like:

• 2.0.0b2 now
• 2.0.0rc0 september 1st
• 2.0.0 september 15th

[jakirkham]

Am I understanding correctly that OSMnx 2.0 will be the first release with NumPy 2 compatibility (and the OSMnx 1.x series will be limited to NumPy 1)?

Sorry if I'm asking something that is clarified elsewhere, had a hard time finding the answer when searching (with the exception of pyproject.toml constraints)

[gboeing]

@jakirkham correct. We're not updating the 1.x branch further (outside of bug fixes or deprecation warnings necessary for transitioning to v2). However, if dependency version incompatibility poses a real problem for the community in the meantime, I'm always happy to review a new issue documenting the problem and proposing a minimal PR to resolve it.

[gboeing]

Beta 2 has been released with:

• support for custom_filter union queries in the graph module
• faster, optimized geometry construction in the features module
• removing the optional gdal dependency and replacing it with rio-vrt
• new buffer_geometry helper function (a small user quality-of-life improvement)