Skip to content

Installation

Prerequisites

If using Martin with PostgreSQL database, you must install PostGIS with at least v3.5+ on PostgreSQL v12+.

On x86_64, the prebuilt binaries and Docker images require a CPU with the x86-64-v3 feature level (AVX2, BMI2, FMA. Meaning Intel Haswell / AMD Excavator, 2013-2015 or newer). Older CPUs can use the static x86_64-unknown-linux-musl-legacycpu tarball or the :latest-legacycpu / :<version>-legacycpu Docker image (linux/amd64 only, no rendering), the x86_64-unknown-freebsd-legacycpu tarball on FreeBSD, or build Martin from source.

The FreeBSD binaries need FreeBSD 14.0 or newer.

Docker

Martin is also available as a Docker image. You could either share a configuration file from the host with the container via the -v param, or you can let Martin auto-discover all sources e.g. by passing a PostgreSQL connection string or the .mbtiles/.pmtiles files or URLs to .pmtiles. A configuration file can read a variable passed into the container, for example connection_string: ${DATABASE_URL}.

export DATABASE_URL=postgres://user:password@host:port/db  # secret!

docker run -p 3000:3000 \
           -e DATABASE_URL \
           -v /path/to/config/dir:/config \
           ghcr.io/maplibre/martin:2.0.0-beta.7 \
           --config /config/config.yaml

Note

The default image is lean and does not include server-side style rendering. If you need it, use the batteries-included -full image variant instead, tagged :latest-full or :<version>-full. It is larger because it bundles the EGL and Mesa libraries rendering needs.

From Binary Distributions Manually

You can download martin from GitHub releases page.

Platform x64 ARM-64
Linux .tar.gz (gnu)
.tar.gz (gnu, full)
.tar.gz (musl)
.deb
.tar.gz (gnu)
.tar.gz (gnu, full)
.tar.gz (musl)
macOS .tar.gz
Windows .zip
FreeBSD .tar.gz .tar.gz

Note

The standard binaries do not include server-side style rendering. The -full Linux-gnu tarballs do. They add the rendering feature and its bundled native libraries.

Rust users can install pre-built martin binary with cargo-binstall and cargo.

cargo install cargo-binstall
cargo binstall martin
martin --help

Verify Release Integrity & Provenance

Starting with recent releases, binaries and packages are signed via GitHub Actions artifact attestations. You can verify that a downloaded asset was built by MapLibre's official CI workflow and has not been tampered with by a third party.

Verify directly against GitHub's attestation API:

gh attestation verify martin-x86_64-unknown-linux-gnu.tar.gz \
    --repo maplibre/martin \
    --signer-workflow maplibre/martin/.github/workflows/release.yml

Replace martin-x86_64-unknown-linux-gnu.tar.gz with the archive or .deb package you downloaded.

Download the provenance.json bundle alongside your release asset to verify without network access:

gh attestation verify martin-x86_64-unknown-linux-gnu.tar.gz \
    --repo maplibre/martin \
    --signer-workflow maplibre/martin/.github/workflows/release.yml \
    --bundle provenance.json

Replace martin-x86_64-unknown-linux-gnu.tar.gz with the archive or .deb package you downloaded.

From package

To install with apt source and others, we need your help to improve packaging for various platforms.

Homebrew

If you are using Homebrew you can install the martin formula from homebrew-core using

brew install martin
martin --help

The formula is maintained by Homebrew and follows stable releases only.

If you installed martin from the former maplibre/martin tap

switch to the homebrew-core formula with

brew uninstall martin
brew untap maplibre/martin
brew install martin

Debian packages (x86_64) manually

curl -O https://github.com/maplibre/martin/releases/latest/download/debian-x86_64.deb
sudo dpkg -i ./debian-x86_64.deb
martin --help
rm ./debian-x86_64.deb

Arch Linux

The AUR carries martin, maintained by the community. With an AUR helper such as yay:

yay -S martin
martin --help

Nix

nixpkgs carries martin, usually a release or two behind.

nix-shell -p martin --run 'martin --help'

Building from source

If you install Rust, you can build martin from source with Cargo:

cargo install martin --locked
martin --help

Optional features

Features prefixed with unstable- are not included in default builds, Homebrew, Debian packages, or the Docker image. To experiment with them, build Martin from source with the feature enabled:

cargo install martin --locked --features=unstable-duckdb

The currently available unstable feature is unstable-duckdb for DuckDB / GeoParquet sources.

Server-side style rendering is also left out of the default feature set. To include it (Linux only), add the rendering feature. Building it needs nothing extra, but running it needs EGL and OpenGL ES (just install-dependencies installs them on Debian and Ubuntu).

cargo install martin --locked --features rendering

For FIPS 140-3 compliant TLS, add the fips feature. It makes rustls use the FIPS-validated AWS-LC module (aws-lc-fips-sys), which needs CMake and Go to build, and Martin refuses to start if that provider is not in FIPS mode.

cargo install martin --locked --features fips

Platform-Specific Build Notes

Windows

When building from source on Windows, please note the following feature limitations: