---
id: haversine
version: "2.9.0"
license: MIT
license_treatment: permissive
maintenance: aging
---

# haversine — Calculate the distance between 2 points on Earth.

License: permissive · Maintenance: aging · Downloads: 4.0M/mo

## What it is and what it does

Haversine is a lightweight Python library that computes the shortest distance between two points on Earth given their latitude and longitude coordinates. It implements the haversine formula, which calculates great-circle distances on a sphere, and supports output in kilometers, meters, miles, nautical miles, feet, inches, radians, and degrees. The package also provides an inverse haversine function to find a destination point given a starting point, distance, and direction.

The core use case is straightforward: pass two (lat, lon) tuples and get a distance back. For bulk operations, the library offers a vector mode that can compute distances between multiple point pairs; this mode optionally uses NumPy for performance and can be further accelerated with Numba and icc_rt. The package is pure Python with no mandatory dependencies, making it easy to integrate into any project that needs basic geographic distance calculations.

Use it for:

- Calculate driving or travel distances between cities or landmarks for routing or trip planning applications.
- Filter nearby locations from a database by computing distances from a user's current position.
- Batch-compute pairwise distances between many geographic points for clustering or spatial analysis.
- Validate geographic coordinates or detect anomalies by checking distances between consecutive GPS readings.
- Find the closest facility (store, hospital, etc.) to a given location by comparing distances to multiple candidates.

## Worth the install?

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

Calculates great-circle distances between geographic coordinates on Earth using the haversine formula, supporting multiple distance units and optional vector operations.

Yes. Haversine is a stable, dependency-free library for a common task. It has no known vulnerabilities, permissive licensing, and low install friction. The aging maintenance status (624 days since last release) is not a blocker for a mature, narrow-scope library—the formula itself does not change. Install it if you need to calculate distances between geographic coordinates; skip it only if you require more advanced geodetic calculations or are already using a larger geospatial framework.

## Install

pip install haversine
uv add haversine
poetry add haversine

## Installing haversine

Before you install: Low friction: pure Python wheel with no runtime dependencies. Maintenance status is aging—last release was 624 days ago, though the repository remains active with recent commits and the package is marked Production/Stable.

License in practice: MIT license is permissive; you can use, modify, and distribute this package freely in commercial and private projects with minimal restrictions.

Quickstart:

pip install haversine

from haversine import haversine, Unit

lyon = (45.7597, 4.8422)
paris = (48.8567, 2.3508)
distance_km = haversine(lyon, paris)
distance_mi = haversine(lyon, paris, unit=Unit.MILES)

Latitude must be in range [-90, 90] and longitude in range [-180, 180]; values outside these ranges will raise an error unless the normalize parameter is used.

Verify before relying:

- Accuracy of haversine formula results compared to other geodetic methods for long distances or polar regions.
- Performance characteristics of vector operations without optional numba and icc_rt dependencies installed.
- Whether the package handles edge cases like antipodal points or coordinates at the poles correctly.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: aging
- Downloads: 4.0M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

haversine distance calculation, latitude longitude distance, geographic distance between points, great circle distance, earth distance formula, coordinate distance calculator, geo distance library, geospatial, distance-calculation, gis

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