{"id":8315,"library":"mgrs","title":"MGRS Coordinate Conversion for Python","description":"The `mgrs` Python library (version 1.5.4) provides a simple `ctypes` wrapper around selected MGRS-related C functions from GeoTrans (version 2.4.2), an internal copy of which is included within the library. It facilitates conversions to and from Military Grid Reference System (MGRS) coordinates and decimal degrees (latitude/longitude), offering various precision levels. The library is actively maintained, with a recent release in February 2026.","status":"active","version":"1.5.4","language":"en","source_language":"en","source_url":"https://github.com/hobuinc/mgrs","tags":["GIS","coordinates","MGRS","geospatial","conversion","ctypes"],"install":[{"cmd":"pip install mgrs","lang":"bash","label":"Install latest stable version"}],"dependencies":[{"reason":"Required for packaging metadata and wheel imports since version 1.3.9.","package":"packaging","optional":false}],"imports":[{"note":"While `import mgrs` works, it's generally cleaner to import the `MGRS` class directly for instantiation.","wrong":"import mgrs; mgrs.MGRS()","symbol":"MGRS","correct":"from mgrs import MGRS"}],"quickstart":{"code":"from mgrs import MGRS\n\nm = MGRS()\n\n# Convert Latitude/Longitude to MGRS\nlatitude = 42.0\nlongitude = -93.0\nmgrs_coords = m.toMGRS(latitude, longitude)\nprint(f\"({latitude}, {longitude}) -> {mgrs_coords}\")\n\n# Convert MGRS to Latitude/Longitude\nlat_lon_coords = m.toLatLon(mgrs_coords)\nprint(f\"{mgrs_coords} -> {lat_lon_coords}\")\n\n# Convert DMS to Decimal Degrees\ndms_str = '321942.29N'\ndec_deg = m.dmstodd(dms_str)\nprint(f\"{dms_str} -> {dec_deg}\")\n\n# Convert Decimal Degrees to DMS\nd, minute, s = m.ddtodms(dec_deg)\nprint(f\"{dec_deg} -> (D:{d}, M:{minute}, S:{s}))\")","lang":"python","description":"This quickstart demonstrates how to initialize the MGRS converter and perform common operations such as converting between latitude/longitude and MGRS, and between Degrees-Minutes-Seconds (DMS) strings and decimal degrees. Precision can also be controlled in `toMGRS()`."},"warnings":[{"fix":"Replace `except RTreeError:` with `except MGRSError:`.","message":"The `RTreeError` exception was deprecated and aliased to `MGRSError` in version 1.4.0. Direct usage of `RTreeError` should be replaced with `MGRSError` for future compatibility.","severity":"deprecated","affected_versions":">=1.4.0"},{"fix":"Upgrade to `mgrs` version 1.3.4 or newer to ensure correct truncation behavior for MGRS coordinates.","message":"Earlier versions (prior to 1.3.4) were reported to incorrectly round MGRS coordinates instead of truncating them, leading to precision errors. MGRS requires truncation.","severity":"breaking","affected_versions":"<1.3.4"},{"fix":"Ensure you have a recent `pip` and Python (>=3.9) to leverage pre-built wheels. If issues persist, verify your C compiler setup or use a Linux/macOS environment.","message":"For older Python environments or manual compilation, the `mgrs` library, being a Ctypes wrapper around C code, historically had complex installation challenges on Windows without pre-built wheels. This is largely mitigated by modern `pip` and wheel distributions.","severity":"gotcha","affected_versions":"<1.5.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"When using PyInstaller, you often need to explicitly include the `mgrs` package's shared libraries in your `.spec` file. A common fix is to add a `datas` entry to copy the `libmgrs*.pyd` file. For example: `datas=[('path/to/venv/Lib/site-packages/mgrs', 'mgrs')]` (adjust paths as necessary to include the `.pyd` file).","cause":"This error typically occurs when using application packagers like PyInstaller on Windows. The underlying shared library (`.pyd` file) for `mgrs` is not correctly located or bundled in the final executable.","error":"mgrs.core.MGRSError: Unable to load libmgrs.cpXX-win_amd64.pyd"},{"fix":"Perform a clean reinstall of the package: `pip uninstall mgrs` followed by `pip install mgrs --no-cache-dir`. Ensure your Python environment meets the `>=3.9` requirement and that no other `mgrs.py` or `mgrs` package shadows the correct one.","cause":"This usually indicates an incomplete or corrupted installation of the `mgrs` package, or a conflict if another package named `mgrs` exists in the Python path. In older versions, it could also stem from failed compilation of the C components.","error":"ImportError: cannot import name 'MGRS' from 'mgrs' (or similar during `import mgrs`)"},{"fix":"Ensure both latitude and longitude are provided as numeric arguments: `m.toMGRS(latitude, longitude)`.","cause":"The `toMGRS` method requires both `latitude` and `longitude` arguments. This error means one or both were omitted or passed incorrectly.","error":"TypeError: toMGRS() missing 1 required positional argument: 'longitude'"}]}