Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–223 runs
build_error
glibcnode 18–223 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Geodesic
✓ import { Geodesic } from 'geographiclib-geodesic'
✗ const Geodesic = require('geographiclib-geodesic').Geodesic
ESM import since v2.0.0. CommonJS require works but without destructuring.
WGS84
✓ const { Geodesic } = require('geographiclib-geodesic'); const geod = Geodesic.WGS84;
✗ import { WGS84 } from 'geographiclib-geodesic'
WGS84 is a static property, not a named export. Use Geodesic.WGS84 or new Geodesic('WGS84').
default import
✓ import geographiclib from 'geographiclib-geodesic'
Default import gives the whole module. Not recommended; prefer named imports.
Solves inverse geodesic (distance & azimuth between two points) and direct geodesic (destination from point, azimuth, distance) using WGS84 ellipsoid, plus polygon area computation.
import { Geodesic } from 'geographiclib-geodesic';
const geod = Geodesic.WGS84;
// Inverse problem: distance and azimuth between two points
const r1 = geod.Inverse(-41.32, 174.81, 40.96, -5.50);
console.log(`Distance: ${r1.s12.toFixed(3)} m`);
console.log(`Azimuth from A: ${r1.azi1.toFixed(8)}°`);
console.log(`Azimuth from B: ${r1.azi2.toFixed(8)}°`);
// Direct problem: point given start point, azimuth, and distance
const r2 = geod.Direct(-32.06, 115.74, 225, 20000e3);
console.log(`Destination: (${r2.lat2.toFixed(8)}, ${r2.lon2.toFixed(8)})`);
console.log(`Final azimuth: ${r2.azi2.toFixed(8)}°`);
// Polygon area (example: simple triangle)
const geodPoly = Geodesic.WGS84;
const poly = geodPoly.Polygon(false);
poly.AddPoint(0, 0);
poly.AddPoint(1, 0);
poly.AddPoint(0, 1);
const result = poly.Compute();
console.log(`Perimeter: ${result.perimeter.toFixed(3)} m`);
console.log(`Area: ${result.area.toFixed(3)} m²`);
Debug
Known issues
breakingVersion 2.0.0 split from monolithic geographiclib package. Imports changed from 'geographiclib' to 'geographiclib-geodesic' and 'geographiclib-dms'.fixUpdate imports: use 'geographiclib-geodesic' for geodesic functions and optionally 'geographiclib-dms' for DMS conversion. The old 'geographiclib' package will be deprecated after 2023-05-01.
affects: <2.0.0
breakingIn v2.0.0, ES module support was added. The package now exports ESM by default. CommonJS require still works but may behave differently in some bundlers.fixFor ESM: use import { Geodesic } from 'geographiclib-geodesic'. For CJS: use const { Geodesic } = require('geographiclib-geodesic'). affects: >=2.0.0
deprecatedThe old monolithic package 'geographiclib' (which included DMS functions) is deprecated after 2023-05-01. Users should migrate to 'geographiclib-geodesic' and optionally 'geographiclib-dms'.fixReplace require('geographiclib') with require('geographiclib-geodesic') and if using DMS, add require('geographiclib-dms'). affects: all versions of geographiclib
gotchaGeodesic.WGS84 is a static property on the Geodesic class, not a separate export. Trying to import { WGS84 } directly fails.fixUse Geodesic.WGS84 after importing { Geodesic }. affects: all
gotchaThe Direct and Inverse methods return objects with many properties (lat2, lon2, azi1, azi2, s12, etc.). Not reading the full result may lead to missing azimuth or distance values.fixAlways store the result and access the needed properties. See documentation for complete list.
affects: all
gotchaCoordinates are in degrees; azimuths are in degrees from north (clockwise). Distances are in meters. No unit conversion is performed.fixEnsure inputs are in degrees and meters as expected. Convert if necessary.
affects: all
Errors
Common errors & fixes
Cannot find module 'geographiclib-geodesic'
Package not installed or incorrect import path after split from geographiclib.
fixRun 'npm install geographiclib-geodesic' and ensure import path is correct: require('geographiclib-geodesic') or import { Geodesic } from 'geographiclib-geodesic'. Geodesic.WGS84 is undefined
Using outdated import from the deprecated 'geographiclib' package where Geodesic was not available.
fixInstall 'geographiclib-geodesic' and import { Geodesic } from 'geographiclib-geodesic'. import { Geodesic } from 'geographiclib-geodesic' works in Node but not in browser (with webpack or parcel)
Webpack may not resolve the package correctly if it's not configured for ESM or if there is a version mismatch.
fixEnsure you are using a bundler that supports ESM (e.g., webpack 5 with experiments.outputModule) or use CommonJS require(). Alternatively, use the browser-ready file from 'geographiclib-geodesic/geographiclib-geodesic.min.js'.
TypeError: geod.Inverse(...) is not a function or returns undefined
The geod object is not a Geodesic instance but the module itself (require returns the whole module).
fixUse const geod = require('geographiclib-geodesic').Geodesic.WGS84 or import { Geodesic } from 'geographiclib-geodesic'; const geod = Geodesic.WGS84; Result latitude is NaN or longitude is NaN
Input coordinates out of range or azimuth/distance not finite.
fixCheck that latitudes are between -90 and 90, longitudes between -180 and 180, azimuth between 0 and 360, distance positive finite.
Audit
Dependencies
geographiclib-dmsoptionaloptional dependency for parsing and formatting DMS coordinates (degrees-minutes-seconds)