Install & Compatibility
Where this runs
tested against v2.0.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.95 runs
build_error
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 11.9s · import 1.826s · 325MB
327MB installed
● package 327MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
osmnx
✓ import osmnx as ox
Standard convention for importing the library.
graph
✓ import osmnx.graph as ox_graph
Accessing specific modules like 'graph' directly is common, but often 'ox.graph' is sufficient.
plot
✓ import osmnx.plot as ox_plot
Accessing specific modules like 'plot' directly is common, but often 'ox.plot' is sufficient.
This quickstart demonstrates how to download a drivable street network for a specified place and then visualize it. It also shows how to enable caching for API requests.
import osmnx as ox
# Configure osmnx to use a cache for API calls
ox.settings.use_cache = True
# Download and model a street network for a place
place = "Piedmont, California, USA"
G = ox.graph.graph_from_place(place, network_type="drive")
# Plot the graph
fig, ax = ox.plot_graph(G)
Debug
Known issues
breakingThe OSMnx 2.0 release (November 2024) introduced significant breaking changes, including a streamlined API, refactored modules, and the removal of previously deprecated functionality. Code written for v1.x will likely require updates to be compatible with v2.x.fixConsult the official OSMnx 2.0 Migration Guide and the Examples Gallery. When running v1.9.x, pay attention to `FutureWarning` messages, which provide guidance for v2.0 compatibility. Many function signatures and module locations have changed.
affects: >=2.0.0
gotchaInstalling OSMnx via `pip` can be challenging on some systems due to its dependencies (e.g., GeoPandas, Shapely, Rasterio) which rely on compiled C/C++ libraries. Compilation issues can arise.fixThe recommended installation method, especially for users encountering issues, is to use `conda` via the `conda-forge` channel (`conda install -c conda-forge osmnx`). Conda handles the complex binary dependencies more reliably.
affects: All versions
gotchaOSMnx heavily leverages NetworkX graphs and GeoPandas GeoDataFrames. Users unfamiliar with these underlying libraries may struggle to effectively use or troubleshoot OSMnx, as its data models are built upon them.fixFamiliarize yourself with the core concepts and data structures of NetworkX and GeoPandas. The OSMnx documentation and examples often assume a basic understanding of these libraries.
affects: All versions
gotchaAs OSMnx retrieves data from OpenStreetMap, all derivative works and visualizations generated using OSMnx must provide proper attribution to OpenStreetMap, in accordance with its open data license.fixAlways include a clear attribution to OpenStreetMap when presenting or publishing data or visualizations derived from OSMnx. Refer to OpenStreetMap's copyright and license guidelines for specifics.
affects: All versions
deprecatedIn recent pandas versions, directly accessing elements of a `pandas.Series` by positional index (e.g., `x[0]`, `x[1]`) within `.apply()` functions for geographic coordinates (latitude/longitude) is deprecated and will raise a `FutureWarning`. This is common in functions like `ox.distance.nearest_nodes`.fixUse `.iloc` for explicit positional indexing (e.g., `x.iloc[0]`, `x.iloc[1]`) to access elements from a `pandas.Series` within `apply` functions, ensuring future compatibility and suppressing warnings.
affects: Pandas >= 2.0 (and OSMnx usage with it)
gotchaOSMnx uses the OpenStreetMap Overpass API for data retrieval. Frequent or very large data requests can lead to hitting API rate limits, which may result in failed queries or temporary IP blocks from the Overpass server.fixEnable and configure OSMnx's caching (`ox.settings.use_cache = True`) to minimize redundant API calls. Design your queries to be as specific and small as possible, and introduce delays between large requests if necessary to avoid overwhelming the API.
affects: All versions
gotchaFor very large graphs, some network analysis functions provided by NetworkX (and consequently used by OSMnx) can be computationally intensive and slow, as NetworkX is primarily a Python-native library.fixFor performance-critical analyses on massive graphs, consider exporting the OSMnx graph to formats compatible with faster graph libraries like `igraph` or `graph-tool` (which have C backends) for specific computational tasks, then re-importing results if needed.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'osmnx'
The `osmnx` package is not installed in the current Python environment, or the environment where it is installed is not active.
fixInstall osmnx using pip or, preferably, conda due to its complex geospatial dependencies: `conda install -c conda-forge osmnx` or `pip install osmnx`.
AttributeError: module 'osmnx' has no attribute 'project_gdf'
This error typically occurs when using an older version of OSMnx where the `project_gdf` function was directly in the main `osmnx` namespace. In newer versions (0.14.0 and above), it was moved to `osmnx.projection.project_gdf`.
fixUpdate OSMnx to the latest version and adjust the call to `ox.projection.project_gdf()`: `gdf = ox.projection.project_gdf(gdf)`.
OSError: Could not find libspatialindex_c library file
This error occurs during OSMnx installation or import, specifically when the `rtree` dependency cannot find the `libspatialindex_c` shared library, which is a system-level geospatial dependency. This is common on Linux and when using pip for installation.
fixFor Debian/Ubuntu, install `libspatialindex-dev`: `sudo apt install libspatialindex-dev`. For macOS, use Homebrew: `brew install spatialindex`. For other systems, consult the `rtree` installation documentation or use `conda` to install OSMnx, as it typically handles these dependencies: `conda install -c conda-forge osmnx`.
ImportError: cannot import name 'TopologicalError' from 'shapely.geos'
This issue arises from an incompatibility between the installed versions of OSMnx and its dependency, Shapely. Specifically, older OSMnx versions (prior to 1.3) are not compatible with Shapely 2.0 or newer.
fixRecreate your environment and install compatible versions. Ensure OSMnx >= 1.3 for Shapely >= 2.0. The recommended approach is to install OSMnx via conda, which manages compatible dependency versions: `conda create -n ox --strict-channel-priority -c conda-forge osmnx`.
NetworkXPointlessConcept: Connectivity is undefined for the null graph
This error from NetworkX (a core dependency of OSMnx) indicates that the `osmnx.graph_from_place()` function (or similar) was unable to find or download any nodes or edges for the specified geographic query, resulting in an empty or 'null' graph. This can happen if the place name is misspelled, ambiguous, or if OpenStreetMap does not have detailed data for that specific location or geometry type.
fixVerify the spelling and specificity of the place name. Try varying the query string, providing a structured query dictionary, or specifying a `which_result` parameter to select a different geocoding result. If a polygon boundary is missing, consider using `osmnx.graph_from_address()` with a `dist` parameter instead.
Upgrade
Version history
2.1.1latest on PyPI · released Jul 21, 2026
Audit
Dependencies
geopandasrequiredCore geospatial data structures and operations.
networkxrequiredCore graph data structures and algorithms.
numpyrequiredNumerical computing.
pandasrequiredData manipulation and analysis.
requestsrequiredHTTP requests to OpenStreetMap APIs.
shapelyrequiredGeometric object manipulation.
matplotliboptionalFor plotting and visualization.
rasteriooptionalFor handling raster data, e.g., elevation models.
scikit-learnoptionalFor spatial indexing and machine learning algorithms, e.g., nearest neighbors.
scipyoptionalFor scientific computing, used in some analysis functions.