PyMappr is a remake of SimpleMappr in Python as an offline desktop application.
- Load points from CSV/TSV/Excel (with a column-mapping step on import), type them in by hand (decimal degrees or DMS), or drop them straight onto the map with click-to-place.
- Group/color/symbol styling by any name column, including two-attribute styling (e.g. color by Family, symbol by Genus) with a compact legend.
- Legend customization: position, columns, marker scale, spacing, and bold / italic / underline for the labels and title.
- ~30 toggleable Natural Earth layers (borders, cities, water, physical features, infrastructure) with automatic 110m/50m/10m detail by zoom.
- Six map projections plus a Globe (orthographic) view and regional Lambert projections, all reprojected live. Drag the globe to spin it.
- Landscape or portrait framing, draggable legend and labels, compass, graticule, and continent presets.
- Projects (
.pymapprfiles) with autosave/restore, and export/import for sharing. - Export the current map as PNG, or as a self-contained Python (matplotlib) or R (ggplot2) script that reproduces it outside PyMappr.
| Portrait | Landscape |
|---|---|
 |
 |
More examples, including bathymetry, boundaries, time zones, and basemap
renders, are in docs/images/.
Any number of name columns followed by Longitude/Latitude, in any order - you confirm the mapping on import:
| Genus | Species | Longitude | Latitude |
|---|---|---|---|
| Eleusis | chapadensis | -68.4349 | -12.3541 |
| Xanthopygus | orinocensis | 67°33'37"W | 10°18'29"N |
Sample datasets in sample_data/ for beetles, seabirds, and
orchids.
Grab the latest build for your platform from the
releases page. Releases are built automatically when a
pull request is merged into main.
| Platform | File | Install |
|---|---|---|
| Windows | PyMappr-Setup-<version>.exe |
Run the installer |
| macOS | PyMappr-<version>-macOS.dmg |
Open and drag to Applications |
| Linux (Ubuntu) | pymappr_<version>_amd64.deb |
sudo apt install ./pymappr_<version>_amd64.deb |
| Linux (Fedora) | pymappr-<version>-1.<dist>.x86_64.rpm |
sudo dnf install ./pymappr-<version>-*.x86_64.rpm |
| Linux (Arch) | pymappr-<version>-1-x86_64.pkg.tar.zst |
sudo pacman -U pymappr-<version>-1-x86_64.pkg.tar.zst |
| Any Linux | PyMappr-<version>-linux-<distro>-x86_64.tar.gz |
Extract and run PyMappr/PyMappr |
The Releases tab is the only official download source.
Requires Python 3.11+ with Tk support.
pip install -r requirements.txt
python scripts/fetch_data.py # one-time data download (~165 MB core;
# add --skip-extras to skip biodiversity/ecoregion overlays)
python -m pymapprpython -m pytest tests/ # coordinate parser + CSV loader + styling tests
python scripts/render_preview.py # headless render smoke test -> preview/*.png
python scripts/make_screenshots.py # regenerate the README imagesProject layout:
pymappr/coords.py- decimal/DMS coordinate parsingpymappr/data_loader.py- CSV/TSV/Excel reading and column mappingpymappr/projects.py- project files, settings, session autosavepymappr/layers.py- Natural Earth layer store and on-disk frame cachepymappr/projections.py- map projections (pyproj)pymappr/renderer.py- matplotlib map renderingpymappr/styles.py- point styles and group/color-by stylingpymappr/updates.py- daily update check against the GitHub releases APIpymappr/app.py,pymappr/ui/- Tkinter applicationscripts/fetch_data.py- downloads and prepares the bundled map datapackaging/- PyInstaller spec, Inno Setup script, Linux/Fedora/Arch packaging
Building the release packages is automated by
build-release.yml; see
packaging/ for local build scripts per platform.
index.html is MiniMappr, a browser-only edition
of PyMappr hosted with GitHub Pages at
calebhendren.github.io/PyMappr. It
covers the core workflow with no install: points from a CSV/TSV (with a
column-mapping step), a pasted table, or manual entry, decimal degrees or DMS,
styled by group/color/symbol on the same projections (Equirectangular, Mercator,
Robinson, Mollweide, Natural Earth, Winkel Tripel, orthographic Globe, and
regional Lambert), exported as PNG or SVG.
It intentionally leaves out the heavier desktop features: the ~30 Natural Earth layers, relief/Blue Marble basemaps, bathymetry, labels, Excel import, project files, and Python/R code export. The page is self-contained (D3, d3-geo-projection, topojson-client, and a simplified world outline are all inlined) and is kept out of the PyInstaller build.
If PyMappr is useful to you, you can support its development on Ko-fi: ko-fi.com/calebhendren
Citing PyMappr is not necessary, but it is welcome:
Hendren, Caleb. PyMappr [computer software]. https://github.com/CalebHendren/PyMappr https://doi.org/10.5281/zenodo.21522496
Map data from Natural Earth (public
domain). The optional Biodiversity & ecoregions overlays - Terrestrial
ecoregions (RESOLVE Ecoregions 2017),
Biodiversity hotspots (Conservation International, 2016.1),
and Marine ecoregions (WWF/TNC MEOW) -
are CC-BY licensed and fetched by scripts/fetch_data.py; if a source is
unavailable, that layer is skipped and the rest of PyMappr works as usual.
MinMappr (the browser version) uses a simplified, Natural Earth-derived world outline from world-atlas (public domain), rendered with D3 and d3-geo-projection and decoded with topojson-client (all ISC licensed).