This document describes how to build GMT from source codes (stable release or development version) on Linux, FreeBSD, OpenBSD, macOS and Windows.
- Build and runtime dependencies
- Getting GMT source codes
- Building GMT source codes
- Setting path
- Advanced instructions
Build and runtime dependencies
GMT is dependent on some software and libraries to run. Please refer to the GMT wiki page for instructions to install these dependencies on various operation systems.
To build GMT, you have to install:
Optionally install these for more capabilities within GMT:
- Ghostscript (Ability to convert PostScript plots to PDF and rasters)
- GDAL (Ability to read and write numerous grid and image formats)
- PCRE or PCRE2 (Regular expression support)
- FFTW single-precision (Fast FFTs, >=3.3 [not needed under macOS])
- GLib GTHREAD support (>=2.32)
- LAPACK (Fast matrix inversion [not needed under macOS])
- BLAS (Fast matrix multiplications [not needed under macOS])
For movie-making capabilities these executables are needed:
For viewing documentation under Linux via
gmt docs, your need
- xdg-open (Unified open for a variety of files)
Install for building GMT documentation and running tests (not required for general use):
- Sphinx (>=1.8, for building the documentation)
- GraphicsMagick (for running the tests)
- Ninja (optional, build system focused on speed)
- pngquant (optional, for optimizing PNG images in the documentation)
Required support data
You also need to download support data:
- GSHHG: A Global Self-consistent, Hierarchical, High-resolution Geography Database (>=2.2.0)
- DCW: The Digital Chart of the World (optional, >=2.0.0)
Getting GMT source codes
The latest stable release of the GMT source codes (filename: gmt-x.x.x-src.tar.gz) are available from GMT repository on GitHub.
If you want to build/use the latest developing/unstable GMT, you can get the source codes by cloning the
GMT repository on GitHub. Here we use
--depth 50 option for a shallow
clone which can reduce the repository size to download.
git clone --depth 50 https://github.com/GenericMappingTools/gmt
You can also get supporting data GSHHG and DCW (filename: gshhg-gmt-x.x.x.tar.gz and dcw-gmt-x.x.x.tar.gz) from the GMT main site.
Extract the files and put them in a separate directory (need not be where you eventually want to install GMT).
Note for developers: Refer to the git workflow tutorial for more detailed instructions on cloning and forking the repository. It is recommended that you use a full clone rather than a shallow clone.
GMT can be built on any platform supported by CMake. CMake is a cross-platform,
open-source system for managing the build process. The building process is
controlled by three configuration files in the
ConfigDefault.cmakeis version controlled and used to add new default variables and set defaults for everyone. You should NOT edit this file.
ConfigUser.cmakeis not version controlled and is used to override basic default settings on a per-user basis.
ConfigUserAdvanced.cmakeis not version controlled and is used to override more advanced default settings on a per-user basis.
GMT provides two template files,
ConfigUserAdvancedTemplate.cmake in the
directory. In that directory, you may copy
ConfigUser.cmake and edit to change basic
installation parameters. For more advanced parameters, you may copy
ConfigUserAdvanced.cmake and edit.
Note for developers: It is necessary to create both
cmakedirectory using the templates provided in order to enable testing. Refer to the section Configuring CMake for testing GMT in the maintenance guide for instructions on setting up
Here is an example of settings you may want to change after copying
set (CMAKE_INSTALL_PREFIX "/opt/gmt") set (GSHHG_ROOT "/path/to/gshhg") set (DCW_ROOT "/path/to/dcw")
For Windows users, a good example is:
set (CMAKE_INSTALL_PREFIX "C:/programs/gmt6") set (GSHHG_ROOT "C:/path/to/gshhg") set (DCW_ROOT "C:/path/to/dcw")
See the additional comments in
cmake/ConfigUserTemplate.cmake for more details.
Now that you made your configuration choices, it is time for invoking CMake. To keep generated files separate from source files in the source tree, you should create a build directory in the top-level directory, where the build files will be generated, and change into your build directory:
mkdir build cd build cmake ..
For Windows users, you need to open a command prompt and run:
NOTE: Commands below are valid only if you have GMT's dependency libraries installed via vcpkg following these instructions.
mkdir build cd build # For x64 build cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_GENERATOR_PLATFORM=x64 # For x86 build cmake .. -DCMAKE_TOOLCHAIN_FILE=C:\vcpkg\scripts\buildsystems\vcpkg.cmake -DCMAKE_GENERATOR_PLATFORM=x86
For advanced users, you can append the option
-G Ninja to use the
build tool Ninja, which is a small build system
with a focus on speed.
Building GMT source codes
In the build directory, type
# Linux/macOS/FreeBSD/OpenBSD cmake --build . # Windows cmake --build . --config Release
which will compile all the programs. You can also append
--parallel [jobs] to enable parallel build, in which
jobs is the maximum number of concurrent processes to use when building. If
jobs is omitted the native build
tool's default number is used.
Note: These instructions build the source code for GMT. Optionally, follow the instructions for building the documentation in the maintenance guide to build the documentation (for example, to develop the documentation or to use
gmt docswithout the GMT server).
Note for developers: Refer to the file
admin/bashrc_for_gmtfor useful aliases for configuring and building GMT.
# Linux/macOS/FreeBSD/OpenBSD cmake --build . --target install # Windows cmake --build . --target install --config Release
will install gmt executable, library, development headers and built-in data to the specified GMT install location. Optionally it will also install the GSHHG shorelines (if found), DCW (if found), UNIX manpages, and HTML documentations.
Depending on where GMT is being installed, you might need
write permission for this step so you can copy files to system directories.
sudo will often do the trick.
Note for developers: Refer to the section Updating the development source codes in the maintenance guide for instructions on how to update the development version of GMT. Also refer to the file
admin/bashrc_for_gmtfor useful aliases for updating the development source code.
Make sure you set the
PATH to include the directory containing the GMT executables
if this is not a standard directory like
For Linux/macOS users, open your SHELL configuration file (usually
and add the line below to it.
Then, you should now be able to run GMT programs.
For advanced users who are interested in building documentation, running tests, or contributing more to GMT, please refer the Maintenance Guide.