Install & Compatibility
Where this runs
tested against v26.6.12 · 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.920 runs
installs and imports cleanly · install 0.0s · import 0.111s · 26MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 2.0s · import 0.100s · 27MB
25MB installed
● package 25MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
LatLon
✓ from pygeodesy.ellipsoidalVincenty import LatLon
✗ from pygeodesy import LatLon
PyGeodesy employs lazy importing and organizes classes within specific submodule models (e.g., `ellipsoidalVincenty`, `ellipsoidalKarney`, `sphericalTrigonometry`). Directly importing a class like `LatLon` from the top-level `pygeodesy` package is incorrect and will result in an `ImportError` or unexpected behavior.
GeoidKarney
✓ from pygeodesy import GeoidKarney
Some top-level utilities are available directly from the `pygeodesy` package, but most geometric classes are found in specific model submodules.
This quickstart calculates the geodesic distance between two points using the Vincenty formulae, which is suitable for ellipsoidal earth models. It demonstrates the direct import of the `LatLon` class from a specific ellipsoidal model submodule and its `distanceTo` method.
from pygeodesy.ellipsoidalVincenty import LatLon
# Define two geographic points (latitude, longitude)
point1 = LatLon(41.49008, -71.312796) # Newport, RI
point2 = LatLon(41.499498, -81.695391) # Cleveland, OH
# Calculate the geodesic distance between the two points
distance = point1.distanceTo(point2)
print(f"Distance between Newport, RI and Cleveland, OH: {distance:,.2f} meters")
Debug
Known issues
gotchaSome powerful functionalities, like those in `ellipsoidalKarney` and `css` modules, critically depend on the `geographiclib` library. While `pygeodesy` itself is pure Python, `geographiclib` is a Python wrapper around a C++ library. Users expecting a fully pure-Python solution for all features might encounter `ImportError` if `geographiclib` is not installed for these specific use cases.fixEnsure `geographiclib` is installed (`pip install geographiclib`) if you plan to use features that rely on it. Check the documentation for specific module dependencies.
affects: All versions where `geographiclib`-dependent features are used.
gotchaPyGeodesy extensively uses lazy importing, organizing classes like `LatLon` and `Cartesian` within specific model submodules (e.g., `ellipsoidalVincenty`, `sphericalTrigonometry`). Attempting to import these classes directly from the top-level `pygeodesy` package (e.g., `from pygeodesy import LatLon`) will typically fail or lead to unexpected behavior.fixAlways import classes from their specific submodules, for example: `from pygeodesy.ellipsoidalVincenty import LatLon` or `from pygeodesy.sphericalNvector import LatLon`.
affects: All versions.
gotchaCertain advanced features, such as some `azimuthal` projections or calculations in `rhumb.solve`, can leverage external Karney's C++ utilities (`GeodSolve`, `RhumbSolve`). While optional, configuring these executables via environment variables (`PYGEODESY_GEODSOLVE`, `PYGEODESY_RHUMBSOLVE`) can provide improved performance or access to specific capabilities not available in the pure Python implementation.fixConsult the PyGeodesy documentation for details on setting up and configuring external Karney C++ utilities if enhanced performance or specific functionality is required.
affects: All versions supporting external C++ utility integration.
gotchaPyGeodesy defines a comprehensive set of specific exception types within its `pygeodesy.errors` module (e.g., `GeodesicError`, `RangeError`, `IntersectionError`). Catching a generic `Exception` may obscure the root cause of issues, such as convergence failures in geodesic calculations, out-of-range coordinate values, or unresolved geometric intersections.fixImplement specific exception handling for relevant `pygeodesy.errors` classes to robustly manage common geodetic failure scenarios and provide clearer diagnostics. For example, `try...except GeodesicError:`.
affects: All versions.
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'pygeodesy'
The 'pygeodesy' package is not installed in the current Python environment, or there's a typo in the import statement.
fixInstall the package using pip: `pip install pygeodesy`
RangeError: lat- or longitude values outside the clip, clipLat, clipLon
Input latitude or longitude values provided to a pygeodesy function or class constructor are outside their valid geodetic range (e.g., latitude > 90 or < -90, longitude > 180 or < -180) or exceed specific function limits.
fixValidate input coordinates to ensure latitudes are between -90 and 90 degrees and longitudes are between -180 and 180 degrees, and conform to any specific function documentation regarding limits.
AttributeError: 'LatLon' object has no attribute 'some_method'
An attempt was made to access a non-existent method or attribute on a pygeodesy object (e.g., a LatLon instance), or to set a read-only property defined by the library.
fixRefer to the official pygeodesy documentation for the specific class or module being used to verify the correct method names and available attributes, ensuring compatibility with the chosen earth model or coordinate type.
ModuleNotFoundError: No module named 'geographiclib'
Certain pygeodesy modules or classes, particularly those using Karney's exact geodesic methods (e.g., `ellipsoidalKarney`), require the 'geographiclib' package, which is not installed.
fixInstall the 'geographiclib' package using pip: `pip install geographiclib`
Upgrade
Version history
26.6.12latest on PyPI · released Jun 13, 2026
Audit
Dependencies
geographicliboptionalRequired for certain advanced functionalities like Cassini-Soldner classes (`css`) and some features within `ellipsoidalKarney` (e.g., LatLon/Cartesian classes and `areaOf`/`perimeterOf` functions). While PyGeodesy is pure Python, `geographiclib` is a Python wrapper around C++ code.
numpyoptionalUsed for optimized array operations and certain geometric calculations. Can be excluded from import via `PYGEODESY_XPACKAGES` environment variable.
scipyoptionalUsed for some interpolation and scientific computing tasks. Can be excluded from import via `PYGEODESY_XPACKAGES` environment variable.