---
id: mercantile
version: "1.2.1"
license: BSD
license_treatment: permissive
maintenance: active
---

# mercantile — Web mercator XYZ tile utilities

License: permissive · Maintenance: active · Downloads: 2.2M/mo

## What it is and what it does

Mercantile is a utility library for working with Web Mercator tiles—the standard XYZ grid system used by web mapping platforms. It provides functions to convert between geographic coordinates (longitude/latitude), spherical Mercator coordinates, and tile indices at various zoom levels. It also handles quadkey encoding (Microsoft's tile naming scheme) and lets you traverse tile hierarchies by finding parent and child tiles.

The library is primarily used by GIS developers, map tile servers, and geospatial analysis tools. It includes both a Python API with named tuples for tiles and bounding boxes, and a command-line interface (via click) for batch operations like generating GeoJSON tile shapes or finding tiles that overlap a given region. The package has been stable since 2014 and sees consistent use in the geospatial ecosystem.

Use it for:

- Convert geographic coordinates to tile indices for web map tile servers or slippy map implementations.
- Generate GeoJSON representations of Web Mercator tiles for visualization or analysis.
- Find which tiles intersect a bounding box or geographic region.
- Navigate tile hierarchies to zoom in/out or find neighboring tiles.
- Encode/decode quadkeys for tile identification in mapping APIs.
- Build command-line tools for tile processing using the mercantile CLI.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Mercantile converts between geographic coordinates, Web Mercator tiles (XYZ), and quadkeys, and provides utilities to navigate tile hierarchies and generate GeoJSON tile shapes.

Yes. Mercantile is a stable, well-maintained library with no known vulnerabilities, minimal dependencies, and a clear purpose. It's the standard choice for Web Mercator tile math in Python. Install it if you're working with tile-based maps or need to convert between geographic and tile coordinate systems.

## Install

pip install mercantile
uv add mercantile
poetry add mercantile

## Installing mercantile

Before you install: Low friction: pure Python wheel with a single lightweight runtime dependency (click). Repository is active with a recent commit (2026-06-29) and has been maintained since its 2014 release.

License in practice: BSD license is permissive; you can use, modify, and distribute this package with minimal restrictions, provided you include the license notice.

Quickstart:

pip install mercantile

import mercantile

# Get upper-left corner of a tile
ul = mercantile.ul(486, 332, 10)
print(ul)  # LngLat(lng=-9.140625, lat=53.33087298301705)

# Get bounding box of a tile
bounds = mercantile.bounds(486, 332, 10)
print(bounds)

Verify before relying:

- Whether the package actively supports Python 3.10+ or only legacy versions (classifiers list Python 2.7 and generic Python 3, but latest release was 2021-04-21)

## Package facts

- License: BSD (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: active
- Downloads: 2.2M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

web mercator tile conversion, xyz tile utilities, quadkey to tile, geographic coordinate to tile, tile bounds and coordinates, spherical mercator math, map tile grid tools, geospatial, mapping, tiles

[View on SkillFed](https://skillfed.io/packages/mercantile) · [View on PyPI](https://pypi.org/project/mercantile/)