Install & Compatibility
Where this runs
tested against v1.2.1 · 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
installs and imports cleanly · install 0.0s · import 0.002s · 18.8MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.7s · import 0.002s · 19MB
17MB installed
● package 17MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
mercantile
✓ import mercantile
tile
✓ mercantile.tile(lng, lat, zoom)
Used to get the XYZ tile for a given longitude, latitude, and zoom.
bounds
✓ mercantile.bounds(x, y, z)
Used to get the geographic bounding box (west, south, east, north) for a tile.
ul
✓ mercantile.ul(x, y, z)
Returns the upper-left (longitude, latitude) coordinate of a tile.
children
✓ mercantile.children(tile, zoom=None)
Returns the child tiles of a given tile, optionally at a specific zoom level.
Tile
✓ mercantile.Tile(x, y, z)
A namedtuple representing an XYZ tile.
LngLat
✓ mercantile.LngLat(lng, lat)
A namedtuple representing a longitude and latitude pair.
This quickstart demonstrates fundamental operations: getting a tile for a given point, retrieving its geographic bounds, finding its upper-left corner, and identifying its children tiles.
import mercantile
# Get the tile containing a specific longitude, latitude, and zoom level
tile = mercantile.tile(-105.0, 40.0, 10)
print(f"Tile: {tile}")
# Get the geographic (longitude and latitude) bounds of a tile
bbox = mercantile.bounds(tile.x, tile.y, tile.z)
print(f"Bounding Box: {bbox}")
# Get the upper-left corner (longitude, latitude) of a tile
ul_corner = mercantile.ul(tile.x, tile.y, tile.z)
print(f"Upper-Left Corner: {ul_corner}")
# Find children tiles at a deeper zoom level
children_tiles = mercantile.children(tile, zoom=11)
print(f"Children tiles (first 2): {children_tiles[:2]}")
Debug
Known issues
breakingMercantile 2.0 (future release) will drop support for Python versions older than 3.0. Running on Python 2.x will issue a `UserWarning` in current versions.fixUpgrade to Python 3.x before migrating to Mercantile 2.0.
affects: < 3.0 (Mercantile 2.0 and later)
breakingIn Mercantile 2.0 (future release), the `Tile` constructor will enforce stricter validation: `x` and `y` tile indexes must be integers and within the valid range (0 to 2 ** zoom). Current versions issue a `FutureWarning` if these conditions are not met.fixEnsure `x` and `y` inputs to `mercantile.Tile` are integers and within the valid tile range for the given zoom level.
affects: 1.2.x (as `FutureWarning`), 2.0 (as error)
breakingThe command line interface (CLI) underwent changes in version 1.2.0 (specifically 1.2a1). The `--bounding-tile` and `--with-bounds` options of the `mercantile tiles` command were removed. A new `mercantile bounding-tile` command was introduced to replace this functionality.fixFor CLI users, use the dedicated `mercantile bounding-tile` command instead of the removed options.
affects: 1.2.0+
gotchaIn Mercantile versions prior to 1.2.1, a missing comma in the `__all__` list could prevent `neighbors` and `parent` functions from appearing in module documentation (e.g., `help(mercantile)`). The functions were callable but discoverability was hampered. This was fixed in 1.2.1.fixUpgrade to Mercantile 1.2.1 or later to ensure proper introspection and documentation for all module functions.
affects: < 1.2.1
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'mercantile'
The 'mercantile' library is not installed in your Python environment or the Python interpreter cannot locate it.
fixInstall the library using pip: `pip install mercantile` or `pip3 install mercantile`.
mercantile.InvalidLatitudeError: Y can not be computed: lat=90
The input latitude provided to a mercantile function (e.g., `mercantile.tile`, `mercantile.xy`) is at or beyond the valid Web Mercator limits (approximately +/- 85.0511 degrees), making it impossible to compute tile coordinates.
fixEnsure that latitude values are within the valid Web Mercator range, typically between -85.0511 and 85.0511 degrees (exclusive of the poles).
mercantile.InvalidZoomError: zoom level must be a positive integer
A non-integer or negative value was provided for the 'zoom' parameter to a mercantile function that expects a positive integer zoom level.
fixProvide a valid positive integer for the zoom level (e.g., 0, 1, 2, ...).
Upgrade
Version history
1.2.1latest on PyPI · released Apr 21, 2021
Audit
Dependencies
No dependency data recorded yet.