PyGMT v0.19.0 released

[yvonnefroehlich]

PyGMT v0.19.0 released

The PyGMT team is delighted to announce the release of PyGMT v0.19.0 just before the holiday season ! This release accompanies the publication of the PyGMT paper , introduces the official PyGMT logo , and adds several new high-level plotting methods and grid-processing functions .

Here are the highlights :

• Nineteenth minor release of PyGMT
• The PyGMT paper has been published in G-Cubed
• PyGMT now has an official logo
• Six new high-level plotting methods and two new grid-processing functions
• New Pythonic Frame and Axis parameter classes for configuring map frames and axes
• Ten new or updated gallery examples and tutorials

The PyGMT paper

Checkout the first PyGMT paper, now published in Geochemistry, Geophysics, Geosystems (G-Cubed)!

Tian, D., Fröhlich, Y., Leong, W. J., Grund, M., Schlitzer, W., Jones, M., Uieda, L., & Luis, J. F. (2026). PyGMT: Bridging Python and the Generic Mapping Tools for Geospatial Visualization and Analysis. Geochemistry, Geophysics, Geosystems, 27(7), e2026GC013105. https://doi.org/10.1029/2026GC013105

The paper describes PyGMT’s design, architecture, Pythonic interface, integration with the scientific Python ecosystem, and community development. Enjoy reading it, try the provided examples on your own, and please consider citing it when using PyGMT in your research.

The official PyGMT logo

PyGMT now has an official logo, thanks to the initial design by @sfrooti and feedback from the PyGMT community! The logo is available in several variants and can be added directly to figures using the new Figure.pygmtlogo method (⁠#4616). Just try it by using the related gallery example (#4715) .

Pythonic Axis and Frame parameter classes

Besides the already existing Box, Pattern, and Position parameter classes, this release introduces the Axis and Frame parameter classes for setting map frames and axes (#4406, #4593, #4589, #4520, #4591). Below you find a simple example comparing the old and new syntax. For more details on the usage have a look the frames tutorial (#4596) .

Old syntax

frame=["xaf+lX", "yaf+lY", "+tTitle"]

New syntax

frame=Frame(
    xaxis=Axis(annot=True, tick=True, label="X"),
    yaxis=Axis(annot=True, tick=True, label="Y"),
    title="Title",
)

New features

• Add Figure.choropleth for plotting choropleth maps (#2798)
• Add Figure.fill_between for filling between two curves (#4679, #4698, #4696, #4692)
• Add Figure.paragraph for typesetting one or multiple paragraphs of text strings (#3709, #4605)
• Add Figure.scalebar for plotting a scale bar on maps (#4015)
• Add Figure.directional_rose for plotting a directional rose on map (#4025, #4702)
• Add Figure.magnetic_rose for plotting a magnetic rose on map (#4051, #4702)
• Add pygmt.grdmask for creating a mask grid from polygons or point coverage (#4463)
• Add pygmt.grdpaste for joining two grids along their common edge (#4399)

Nice enhancements

• BREAKING Raise GMTTypeError exception for unsupported image dtypes (#4673)
• Add a note / warning that PS_CONVERT is not supported (#4342)
• Implement the frame="none" syntax for no frames (#4404)
• Add filtering tags for gallery examples of projections (#4643)
• Figure.colorbar: Add parameters dpi, monochrome (#4501, #4499)
• Figure.colorbar: Add parameters label, unit, annot, tick, grid and more to set colorbar annotations and labels (#4407)
• Figure.grdview: Add parameters smooth and surftype, dpi, mesh_fill, nan_transparent, monochrome to control surface types (#4234, #4444)
• Figure.subplot: Add parameters tag, tag_box, tag_position, tag_orientation, tag_number_style, tag_font for controlling subplot tagging (#4313)
• Figure.ternary: Support Frame’s xaxis, yaxis, zaxis attributes to set axis settings for a, b, c axes (#4517)
• Figure.ternary: Add the no_clip parameter for plotting symbols outside the ternary diagram (#4707)
• Figure.text: Allow passing a sequence of offset to the offset parameter (#4652)
• Support passing np.timedelta64 to parameters that expect a sequence (e.g., region) (#4358)
• pygmt.grdfilter: Add parameters filter, width, highpass to set the filter and support Pythonic arguments for distance (#4401, #4405)
• pygmt.grdgradient: Add parameters normalize, norm_ambient, norm_amp, norm_sigma, norm_offset for normalization (#4365)
• pygmt.which: Support long-form arguments for the download parameter (#4429)
• Add the Spilhaus projection to the supported GMT projections (#4657)

Read through the ⁠changelog for the full list of changes. Installation and upgrade instructions are available at Installing — PyGMT . The minimum supported versions of NumPy, pandas, and Xarray have been updated to NumPy 2.1, pandas 2.3, and Xarray 2024.7, respectively, following our support policy for package dependencies. Go try it online at try-gmt . As usual, please feel free to report any bugs with the issue template on GitHub. Your feedback is what helps us to improve !

Additions and updates to gallery examples and tutorials

This release includes ten new or updated gallery examples and tutorials:

• Add advanced tutorial for plotting features on a 3-D surface (#4466)
• Add gallery example for creating a 3-D bar plot (#4315)
• Update gallery example for creating a choropleth map using the high-level method Figure.choropleth (#2798)
• Add gallery example showing how to fill the area between two curves (#3168)
• Add basic tutorial for plotting single-parameter symbols (#3598)
• Update gallery example for plotting scalebars using the high-level method Figure.scalebar(#4382)
• Add gallery example for plotting directional roses (#4010)
• Add gallery example for plotting magnetic roses (#4381)
• Add gallery example for plotting the PyGMT logo (#4715)
• Update basic tutorial for adjusting the map frame using the Axis and Frame parameter classes (#4596)

Features on a 3-D surface	3-D bar plot	Choropleth map (high-level method)

Filling the area between two curves	Plotting single-parameter symbols

Scalebars (via high-level method)	Directional roses (via high-level method)	Magnetic roses (via high-level method)

Roadmap to future releases

The PyGMT team will continue developing high-level plotting methods, improving Pythonic interfaces, wrapping additional GMT modules, and expanding the documentation. There are still plenty of features and improvements where community contributions would be welcome. Check out the good first issue label on GitHub or the list below for things you can help with!

• Features/enhancements
  • Wrap GMT modules: clip, coupe, earthtide, fitcircle, movie, polar, and sac
  • Implement high-level methods of Figure.plot and Figure.plot3d (#2797): Figure.scatter (#3602), Figure.errorbar, Figure.stem
• Documentation improvements
  • Add a beginner friendly PyGMT tutorial that is a good roadmap for new GMT/PyGMT users (#770)
  • Add a tutorial explaining the generally accepted input types (#1268)

Please don’t be shy to reach out on GitHub if you’re interested in contributing ! You can have a look at our Contributors Guide to figure out how you can help and get started .

Deprecations and breaking changes

This release removes several parameters that were deprecated in earlier releases:

• pygmt.grdclip: Remove parameter new (deprecated since v0.15.0) (#4343)
• pygmt.grdfill: Remove parameter mode / no_data (deprecated since v0.15.0) (#4345, #4344)
• utils.sequence_join: Remove parameter separator (deprecated since v0.17.0) (#4346)

This release also includes several changes to exception handling:

• Unsupported image data types now raise GMTTypeError
• Deprecated or conflicting parameters now raise GMTParameterError instead of GMTInvalidInput
• Input arrays with inconsistent sizes now raise GMTValueError

Upcoming deprecations

• v0.20.0 (Planned for September 2026) (Sorry, but in a long term aproach this will make the names more consistent and intuitive, and they will align with with the PEP 8 style guide)
  • pygmt.grdfill: Deprecate parameters constantfill/gridfill/neighborfill/splinefill to constant_fill/grid_fill/neighbor_fill/spline_fill (since v0.18.0)
  • pygmt.grdlandmask: Deprecate parameters bordervalues/ maskvalues to broder_values/mask_values (since v0.18.0)
  • Figure.grdview: Deprecate parameters contourpen/facadepen/meshpen to contour_pen/facade_pen/mesh_pen (since v0.18.0)
  • Figure.grdview: Deprecate parameter drapegrid to drape_grid (since v0.18.0)
  • Figure.histogram: Deprecate parameter barwidth to bar_width (since v0.18.0)
  • Figure.inset: Deprecate parameter margin to clearance (since v0.18.0)
  • Figure.meca: Deprecate parameters compressionfill/ extensionfill to compression_fill/extension_fill (since v0.18.0)
  • Figure.meca: Deprecate parameter labelbox to label_box (since v0.18.0)
  • pygmt.select: Deprecate parameter gridmask to mask_grid (since v0.18.0)
  • pygmt.select: Deprecate parameter mask to mask_values (since v0.18.0)
  • pygmt.surface: Deprecate parameter maxradius to max_radius (since v0.18.0)
  • Figure.velo: Deprecate parameters uncertaintyfill to uncertainty_fill (since v0.18.0)
  • Figure.wiggle: Deprecate parameters fillnegative/ fillpositive to negative_fill/positive_fill (since v0.18.0)
  • pygmt.x2sys_cross: Deprecate parameter trackvalues to track_values (since v0.18.0)
  • Remove deprecated pygmt.io.load_dataarray (since v0.16.0)
  • Session.virtualfile_in: Remove deprecated parameters required_z/extra_arrays/required_data (since v0.16.0)
• v0.21.0
  • pygmt.grdsample: Deprecate parameter translate to toggle (since v0.18.0)
• v0.23.0
• Figure.set_panel: Deprecate parameter fixedlabel to tag (since v0.19.0)
• v1.0.0
  • Short form aliases (e.g. R) will not work if long form aliases (e.g. region) are available (SyntaxWarning raised since PyGMT v0.4.0, see #1316)

The compatibility matrix for GMT, Python, and the required core package dependencies NumPy, pandas, and Xarray is listed at Minimum Supported Versions — PyGMT, so make sure you keep things up to date!

Conference presentations / workshops / sprints

What conferences would you like to see GMT/PyGMT at next? IGARSS? FOSS4G? Are you interested in helping to organize a workshop? Let us know in the comments below!

P.S. Share the word on Instagram @genericmappingtools and ResearchGate!