VersaTiles is a Rust-based tool for processing and serving tile data efficiently. It supports multiple tile formats and offers functionalities for seamless tile handling.

• Installation
  • Linux
  • MacOS
  • NixOS
  • Docker
  • npm (Node.js)
  • Building with Cargo
  • Building from Source
  • Verifying a Release Download
• Quick Start
• Usage
  • Core Concepts
  • Commands
  • VersaTiles Pipeline Language
  • Data Source Syntax
• Configuration
• GDAL Support
• Development
  • Prerequisites
  • Setup
  • Development Workflow
  • Pre-commit Hooks (Recommended)
  • Node.js Bindings Development
  • Contributing
• Repository Structure
• Using as a Library
• Additional Information
• For Maintainers
• License

Install VersaTiles using the provided installation script (that downloads the correct precompiled binary):

curl -Ls "https://github.com/versatiles-org/versatiles-rs/releases/latest/download/install-unix.sh" | sudo sh

That installs the latest stable release. To install a particular one — say, a release candidate — append its tag: … | sudo sh -s v5.0.0-rc.3.

Install VersaTiles via Homebrew:

brew tap versatiles-org/versatiles
brew trust versatiles-org/versatiles
brew install versatiles

VersaTiles is available via nixpkgs (starting from version 24.05):

Add this snippet to configuration.nix:

environment.systemPackages = with pkgs; [ versatiles ];

Alternatively, use it in a shell environment:

{ pkgs ? import <nixpkgs> {} }:

pkgs.mkShell {
  buildInputs = with pkgs; [ versatiles ];
}

Find more details on Nix search.

Pull the latest Docker image for easy deployment:

docker pull versatiles/versatiles

Install the Node.js bindings for use in JavaScript/TypeScript projects:

npm install @versatiles/versatiles-rs

Test upcoming features with prerelease tags:

# Alpha (bleeding edge)
npm install @versatiles/versatiles-rs@alpha

# Beta (feature complete, testing)
npm install @versatiles/versatiles-rs@beta

# Release Candidate (final testing)
npm install @versatiles/versatiles-rs@rc

See all available versions:

npm view @versatiles/versatiles-rs versions

Ensure you have Rust installed, then run:

cargo install versatiles

Clone the repository and build VersaTiles manually:

git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs
cargo build --bin versatiles --release
cp ./target/release/versatiles /usr/local/bin/

# Install system dependencies and Rust
sudo apt-get update
sudo apt-get install -y build-essential pkg-config git curl
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

# Clone, install GDAL, and build
git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs
./scripts/install-gdal.sh
cargo build --bin versatiles --release -F gdal

# Add to PATH
sudo ln -sf "$(pwd)/target/release/versatiles" /usr/local/bin/versatiles

Every released tarball ships with a .sha256 beside it, which both install scripts check before unpacking. A checksum only proves the archive arrived intact, though — it is served from the same place as the archive, so it does not tell you who built it.

Each tarball also carries a signed build provenance attestation: a Sigstore keyless signature recording the commit, workflow and runner that produced it. To check one:

gh attestation verify --owner versatiles-org versatiles-linux-gnu-x86_64.tar.gz

That fails on an archive someone rebuilt or modified, even if its checksum file was replaced to match.

Get started with VersaTiles in 3 steps:

versatiles --version

# Download a small region (Berlin, ~60MB)
versatiles convert --bbox=13.0,52.3,13.8,52.7 --bbox-border=3 https://download.versatiles.org/osm.versatiles berlin.versatiles

# View tile information
versatiles probe berlin.versatiles

# Serve tiles locally
versatiles serve berlin.versatiles

# Access at http://localhost:8080

Convert tile formats:

versatiles convert input.mbtiles output.versatiles

Filter by zoom level:

versatiles convert --min-zoom=5 --max-zoom=12 input.versatiles output.versatiles

Extract a region:

versatiles convert --bbox=13.0,52.3,13.8,52.7 world.versatiles berlin.versatiles

VersaTiles works with tile containers - files or directories containing map tiles organized by zoom level (z), column (x), and row (y).

Supported formats:

✅ = supported, ❌ = not supported. Remote read over HTTP/HTTPS and SFTP read/write require the streamable single-file formats (.versatiles, .pmtiles); SFTP also requires the sftp feature. All formats store opaque tile blobs, so each works with both vector and raster tiles.

Remote access: VersaTiles can read remote .versatiles and .pmtiles files via HTTPS, and write to remote servers via SFTP (requires sftp feature):

versatiles serve https://download.versatiles.org/osm.versatiles

SFTP connections verify the server's host key against ~/.ssh/known_hosts before authenticating, following OpenSSH's accept-new policy:

• Host already known, key matches — connect.
• Host not known yet — record the key and connect, so a first connection is not a dead end. The new entry is appended; the rest of the file is left untouched.
• Host known, key differs — refuse to connect. Either the server was rebuilt, or the connection is being intercepted. If the change was expected, remove the stale line from known_hosts.

VERSATILES_SFTP_KNOWN_HOSTS points at a different file, or disables verification entirely when set to off — appropriate only for a host whose key changes by design, and it gives up the protection against a man-in-the-middle, including the password sent by URL authentication.

Run versatiles to see available commands:

Usage: versatiles [OPTIONS] <COMMAND>

Commands:
  convert  Convert between different tile containers
  probe    Show information about a tile container
  reduce   Reduce a tileset to what a style actually draws
  serve    Serve tiles via HTTP
  help     Show detailed help
  mosaic   Tile and assemble image mosaics
  dev      Some unstable developer tools

Convert tiles between formats, filter by region or zoom, and transform coordinates.

Basic conversion:

versatiles convert input.mbtiles output.versatiles

Advanced options:

How the output is written. A conversion builds its output beside the destination, under a .<name>.tmp name, and moves it into place as the last step. The destination therefore only ever holds a complete container: a conversion that fails part-way leaves whatever was there before exactly as it was, and leaves nothing new behind. (A crash leaves the .tmp behind; the next run to that destination clears it.) Writing to a new path costs no extra disk — the bytes live under one name and the move is free — but overwriting an existing output holds both copies until the move completes.

Writing to a directory replaces its entire contents, so a re-run over a smaller area cannot leave tiles from a previous run mixed in with the new ones. Because that deletes whatever else is inside, an existing non-empty directory is refused unless you pass --force. Overwriting a file needs no such flag: that is atomic, and the previous output survives until the new one is complete.

If a conversion finishes writing but could not read every tile, the output is complete and readable but missing tiles. It is kept as <name>.incomplete.<ext> rather than published or deleted — the destination is untouched, and nothing downstream can mistake the partial result for the conversion that was asked for.

The output path can also be an SFTP URL (sftp://[user[:pass]@]host[:port]/path) to write directly to a remote server. This requires the sftp feature. Only formats that support streaming writes (.versatiles, .pmtiles) are supported over SFTP.

Remote writes follow the same rule: the upload goes to .<name>.tmp beside the destination and is moved into place at the end, so a failed upload never leaves a corrupt file under the name clients are fetching. Replacing an existing remote file is not a single step — SFTP's rename refuses an existing target — so the old one is moved to .old first and removed once the new one is in place. There is a brief moment where the destination does not exist; what cannot happen is losing the previous upload, which is restored if the move fails.

Real-world examples:

# Extract city region from world tiles
versatiles convert --bbox=13.0,52.3,13.8,52.7 \
  world.versatiles berlin.versatiles

# Compress tiles with maximum compression
versatiles convert --compress=brotli \
  uncompressed.tar compressed.versatiles

# Convert image format for smaller file size
versatiles convert --tile-format=webp \
  tiles.mbtiles tiles-webp.versatiles

# Fix coordinate system (TMS to XYZ)
versatiles convert --flip-y \
  tms-tiles.mbtiles xyz-tiles.versatiles

# Remote conversion with zoom filtering
versatiles convert --min-zoom=1 --max-zoom=10 \
  https://download.versatiles.org/osm.versatiles \
  local-osm-filtered.versatiles

# Write directly to a remote server via SFTP (requires sftp feature)
versatiles convert tiles.mbtiles \
  sftp://user@host/path/to/output.versatiles

Analyze tile containers to understand their contents and structure.

Basic usage:

versatiles probe tiles.versatiles

Depth levels:

Probe options:

Examples:

# Quick metadata check
versatiles probe tiles.versatiles -d

# Find actual zoom range with tiles
versatiles probe tiles.versatiles -dd

# Deep inspection with MVT validation
versatiles probe tiles.versatiles -ddd

# Probe remote container
versatiles probe https://download.versatiles.org/osm.versatiles -d

When -ddd reports MVT spec issues the output includes a fix: line suggesting the correct vector_repair invocation. To apply repairs:

# fix structural issues and polygon winding in one pass
versatiles convert \
  '[,vpl](from_container filename="bad.versatiles" | vector_repair)' \
  fixed.versatiles

# also drop features whose geometry cannot be decoded
versatiles convert \
  '[,vpl](from_container filename="bad.versatiles" | vector_repair drop_offenders=true)' \
  fixed.versatiles

A tileset carries every layer, property and feature any style might ask for. A map that ships one style needs far less than that. The VersaTiles colorful style reads name and no name_* at all, so every translation in a Shortbread tileset can go; several layers are drawn as plain geometry and need no properties whatsoever.

reduce reads a MapLibre style, works out what it actually draws, and renders a VPL pipeline that keeps only that.

Basic usage:

versatiles reduce --style colorful.json tiles.versatiles reduced.versatiles

Reduce options:

Seeing the pipeline before running it:

--print writes the pipeline rather than executing it, so the reduction can be reviewed, edited, or kept in a .vpl file as the source of truth:

versatiles reduce --print -s colorful.json tiles.versatiles

Because inline VPL is a first-class input, the printed pipeline pipes straight into convert:

versatiles reduce --print -s colorful.json tiles.versatiles \
  | versatiles convert "[,vpl]-" reduced.versatiles

The work is done by the vector_reduce_to_style pipeline operation, so the same reduction can be written directly in VPL without going through this subcommand:

versatiles convert \
  '[,vpl](from_container filename="tiles.versatiles" | vector_reduce_to_style style="colorful.json")' \
  reduced.versatiles

What it guarantees: the reduction may keep features the style never draws, but never drops one it does. Anything in the style that cannot be interpreted — an expression outside the filter vocabulary, say — widens to "keep" rather than being ignored. Zoom levels are clamped to the tileset's own pyramid, so a style drawing a layer from z17 against a tileset that stops at z14 keeps that layer's features in the z14 tiles rather than dropping them.

Run a local or production tile server with advanced configuration.

Basic usage:

versatiles serve tiles.versatiles
# Access at http://localhost:8080

Server options:

--cache-control defaults to public, max-age=2419200, no-transform: four weeks, right for a public tile server. Set something shorter when the tiles behind a URL change.

--minimal-recompression, --disable-api and --follow-symlinks can be given on their own or with true/false; left out, the configuration file decides. Put a bare switch after the tile sources or before another option — a tile source directly after it would be read as its value.

With --port 0 the server binds a free port chosen by the operating system and prints it to stdout as VERSATILES_PORT=<port> before serving, so a wrapper script can discover where it landed.

By default a symlink in a folder served with --static may not resolve outside that folder: ln -s /etc/passwd public/passwd makes GET /passwd a request for a file the operator never put there, and the path is only checked as text. Symlinks that stay inside the folder work either way — their target is being served anyway. Pass --follow-symlinks to serve a tree of links deliberately.

Tiles and static files are sent with an ETag, so a client or cache whose copy has expired can revalidate it with If-None-Match and get an empty 304 Not Modified while the data is unchanged. The tag is weak: it is derived from the stored bytes, so it is the same for every content encoding and changes whenever the data does.

Custom tile IDs:

Assign custom IDs to tile sources using bracket syntax:

# Bracket prefix: [id]source
versatiles serve [osm]tiles.versatiles

# Bracket suffix: source[id]
versatiles serve tiles.versatiles[osm]

Access tiles at http://localhost:8080/tiles/{id}/{z}/{x}/{y} (an extension such as .pbf may be appended) and the TileJSON at http://localhost:8080/tiles/{id}/tiles.json.

Static content serving:

# Serve tar archive at root
versatiles serve -s "static.tar.br" tiles.versatiles

# Serve with custom prefix
versatiles serve -s "[/assets]static.tar.gz" tiles.versatiles
# Access: http://localhost:8080/assets/...

# Multiple static sources (first match wins)
versatiles serve \
  -s "[/styles]styles.tar.br" \
  -s "[/fonts]fonts.tar.gz" \
  tiles.versatiles

Supported static formats: .tar, .tar.gz, .tar.br, .tar.zst, directories

Remote serving:

.versatiles and .pmtiles containers can be served from https://, http:// or sftp:// URLs; .mbtiles, .tar and directories have to be local.

# Serve remote tiles directly
versatiles serve https://download.versatiles.org/osm.versatiles

# Mix local and remote sources
versatiles serve \
  [local]local.versatiles \
  [osm]https://download.versatiles.org/osm.versatiles

Configuration file:

For production deployments, use YAML configuration (see Configuration section):

versatiles serve -c production.yaml

For a full description of all configuration options:

versatiles help config

Hot-reload (Linux/macOS):

When started with -c, the server reloads its configuration without downtime on SIGHUP:

# Reload after editing production.yaml
kill -HUP $(pidof versatiles)

Tile sources are updated incrementally (unchanged sources keep serving in-flight requests). Static sources are swapped atomically. In-flight requests always complete against the version they started with.

Experimental tools for tile analysis and debugging.

measure-tile-sizes - Generate a visual heatmap of tile sizes:

versatiles dev measure-tile-sizes tiles.versatiles output.png

# With options
versatiles dev measure-tile-sizes \
  --level=14 \
  --scale=4 \
  tiles.versatiles output.png

Output: PNG image where brightness = 10*log2(tile_size). Use to identify large tiles or data quality issues.

export-outline - Export tile coverage as GeoJSON:

versatiles dev export-outline tiles.versatiles coverage.geojson

# Specify zoom level (default: max zoom)
versatiles dev export-outline --level=10 tiles.versatiles coverage.geojson

Output: GeoJSON polygon showing which areas have tiles. Useful for visualizing coverage in QGIS/Mapbox.

print-tilejson - Print TileJSON metadata:

# Compact JSON
versatiles dev print-tilejson tiles.versatiles

# Pretty-printed JSON
versatiles dev print-tilejson -p tiles.versatiles

Output: Standard TileJSON 3.0.0 format with attribution, bounds, zoom levels, etc.

Get detailed help for specific topics:

# Pipeline language reference
versatiles help pipeline

# Configuration file reference
versatiles help config

# Data source syntax (bracket notation, inline VPL, JSON)
versatiles help source

# Raw markdown output (for documentation)
versatiles help pipeline --raw

The VersaTiles Pipeline Language (VPL) allows you to define tile-processing pipelines. Operations include merging multiple tile sources, filtering, and modifying tile content.

Example of combining multiple vector tile sources:

from_merged_vector [
   from_container filename="world.versatiles",
   from_container filename="europe.versatiles" | filter level_min=5,
   from_container filename="germany.versatiles"
]

Run a pipeline from a .vpl file or inline via the [,vpl](…) source syntax, writing the result to a local or remote target or serving it live:

# read a remote pmtiles, drop high zoom levels, write the result back to SFTP
versatiles convert \
  '[,vpl](from_container filename="https://example.org/planet.pmtiles" | filter level_max=8)' \
  sftp://user@fileserver.example.org/tiles/overview.versatiles

# merge a remote base map with a local overlay and serve it live
versatiles serve '[,vpl](from_merged_vector [
  from_container filename="https://download.versatiles.org/osm.versatiles",
  from_container filename="local-overlay.versatiles"
])'

See Data Source Syntax for inline pipelines and versatiles help source for remote/SFTP details.

More details can be found in versatiles_pipeline/README.md.

All commands accept flexible data source expressions. You can override the auto-detected name and container type using bracket notation:

[name,type]path     # prefix notation
path[name,type]     # postfix notation

This also enables inline VPL pipelines — define a pipeline directly on the command line without creating a .vpl file:

versatiles convert \
  "[,vpl](from_container filename='input.versatiles' | filter level_max=12)" \
  output.versatiles

Run versatiles help source for the full syntax reference including JSON format.

For production deployments, use YAML configuration files for fine-grained control over the tile server.

server:
  ip: 0.0.0.0
  port: 8080
  minimal_recompression: false # true = faster, larger responses
  disable_api: false # true = disable /api endpoints

tiles:
  - name: osm
    src: "./tiles/osm.versatiles"
  - name: satellite
    src: "https://tiles.example.com/sat.versatiles"

static:
  - src: "./static"
    prefix: "/"

Start with config:

versatiles serve -c config.yaml

CORS Configuration - Control cross-origin access:

cors:
  allowed_origins:
    - "https://example.org" # Exact origin
    - "https://*.dev.example.org" # Any subdomain
    - "https://example.org:*" # Any port on that host
    - "null" # Sandboxed iframes, file://
    - "/^https://.*\\.example\\.org$/" # Regex, anchored
  max_age_seconds: 86400

The first four forms are matched on the parts of an origin — scheme, host labels, port — so they cannot be extended from either end.

Any other use of * is refused at startup, and the error names a replacement. Versions before 5.0 accepted open-ended globs that matched on raw string edges: https://example.* also allowed https://example.attacker.test, *example.org allowed https://notexample.org, and a scheme-less *.example.org allowed http:// as well as https://. Use https://*.example.org for subdomains and https://example.org:* for ports. A regex must be anchored with ^...$; /example\.org/ is refused.

Custom Response Headers - Add caching and CDN headers:

extra_response_headers:
  Cache-Control: "public, max-age=86400, immutable"
  Surrogate-Control: "max-age=604800" # For Varnish
  CDN-Cache-Control: "max-age=604800" # For CDNs

Every response carries X-Content-Type-Options: nosniff by default, so a browser uses the Content-Type the server sent instead of guessing from the bytes — a file with an unknown extension is served as application/octet-stream, and a browser left to guess may decide it is HTML. Setting the header in extra_response_headers overrides the default.

Multiple Tile Sources - Serve multiple tile sets:

tiles:
  # Local file
  - name: city
    src: "./city.versatiles"

  # Remote HTTPS
  - name: osm
    src: "https://download.versatiles.org/osm.versatiles"

  # MBTiles format
  - name: elevation
    src: "./terrain.mbtiles"

  # VPL pipeline (processed on-the-fly)
  - name: processed
    src: "./pipeline.vpl"

Access tiles at: http://localhost:8080/tiles/{name}/{z}/{x}/{y}

Static Content - Serve styles, fonts, and sprites:

static:
  # Tar archive at root
  - src: "./static.tar.br"
    prefix: "/"

  # Directory at custom path
  - src: "./public"
    prefix: "/assets"

Supported formats: directories, .tar, .tar.gz, .tar.br, .tar.zst

server:
  ip: 0.0.0.0
  port: 8080
  minimal_recompression: false

cors:
  allowed_origins:
    - "https://myapp.com"
    - "https://*.myapp.dev"
  max_age_seconds: 86400

extra_response_headers:
  Cache-Control: "public, max-age=86400"

tiles:
  - name: basemap
    src: "https://download.versatiles.org/osm.versatiles"
  - name: satellite
    src: "./satellite.mbtiles"

static:
  - src: "./styles.tar.br"
    prefix: "/styles"
  - src: "./fonts.tar.gz"
    prefix: "/fonts"

For complete configuration documentation, see:

• versatiles/CONFIG.md - Full reference (auto-generated)

Or run:

versatiles help config

These accept the same values on every subcommand:

The flag wins where both are set.

VersaTiles supports the following environment variables:

• VERSATILES_CACHE_DIR - Enable disk-based tile caching. This is useful if you want to convert large tile sets with the from_gdal_raster VPL operation but have limited memory. Example: VERSATILES_CACHE_DIR=/tmp/versatiles_cache
• VERSATILES_SSH_IDENTITY - SSH identity (private key) file used for SFTP authentication.
• VERSATILES_MAX_TILES - Refuse a conversion whose pyramid holds more than this many tiles (default 10000000000). Guards against a source advertising a pyramid too deep to ever finish. Set to 0 to disable.
• VERSATILES_MEMORY_LOG_SECS - Interval in seconds for logging the process's resident memory during long commands (default 60); set to 0 to disable. Reads /proc/self/status, so it is Linux-only and a no-op elsewhere. Useful when a conversion is being killed by the OOM killer, which the process cannot report itself.

Network resilience for remote reads/writes (HTTP and SFTP) over long-running transfers:

• VERSATILES_NET_MAX_RETRIES - Retries after the first attempt for each network read/write (default 32).
• VERSATILES_NET_RETRY_BASE_MS - Initial retry backoff in milliseconds; doubles each retry (default 1000).
• VERSATILES_NET_RETRY_MAX_MS - Upper bound for a single retry backoff in milliseconds (default 60000). With the defaults, a single operation tolerates roughly 25–30 minutes of continuous failure before giving up, so a long unattended transfer survives a storage/CDN outage instead of aborting.

SFTP connection tuning:

• VERSATILES_SFTP_TIMEOUT_MS - Per-operation SFTP API timeout in milliseconds (default 30000). Raise it if you see "API timeout expired" / "draining incoming flow" errors on congested links.
• VERSATILES_SFTP_KEEPALIVE_SECS - TCP and SSH keepalive interval in seconds (default 15), keeping connections alive across idle gaps.
• VERSATILES_SFTP_MAX_CONNECTIONS - Maximum number of pooled SFTP connections per server.
• VERSATILES_SFTP_KNOWN_HOSTS - Known-hosts file used to verify SFTP server keys (default ~/.ssh/known_hosts). Set it to off to skip verification, which also skips the protection against a man-in-the-middle. See SFTP host keys.

Memory for tile-gathering operations:

• VERSATILES_MAX_TILES_IN_FLIGHT - Upper bound on the number of raw source tiles held in memory at once by operations that combine sources (from_merged_vector, from_stacked, from_stacked_raster); default 2048. Peak memory ≈ this × the largest tile size, so lower it for very large tiles or many sources (e.g. 512), or raise it for more read-ahead on small tiles.
• VERSATILES_OVERVIEW_CACHE_MB - Memory in megabytes for the block cache raster_overview and dem_overview build lower zoom levels through (default 2048). Half of it is reserved for blocks a traversal has already scheduled a consumer for, which is what lets a depth-first conversion build every tile exactly once; the rest is split evenly across zoom levels, keeping the low zooms — the ones that cost the most to rebuild — resident. Raise it if a conversion warns that the reserved half is full, which means some blocks are being built twice.
• VERSATILES_OVERVIEW_REQUEST_TILES - Ceiling on how many source tiles one single-tile request may read while raster_overview or dem_overview builds it (default 16384); 0 removes it. The cost is counted before anything is read, so a request over the ceiling is refused at once. Building a low zoom level on demand costs up to 256 x 4^(levels below the base) source tiles, and the whole base level for zoom 0, so over a dense source a request for a very low zoom is work for a conversion rather than for someone waiting on a response. Bulk streaming — what a conversion does — is never limited.

Memory for reading containers (PMTiles / VersaTiles):

• VERSATILES_CHUNK_MAX_BYTES - Maximum size of a single coalesced byte-range read when streaming tiles, in bytes (default 67108864 = 64 MiB). Each chunk is read as one in-memory blob.
• VERSATILES_CHUNK_READ_MEMORY - Budget for total in-flight chunk-read bytes (default 268435456 = 256 MiB). The number of chunks read concurrently is budget / chunk_size, so peak read memory stays near this value regardless of CPU count. Lower it on memory-constrained machines, or raise it to read further ahead on fast links.
• VERSATILES_MAX_DECOMPRESSED_BYTES - Ceiling on the result of a single decompression, in bytes (default 268435456 = 256 MiB); 0 removes it. Compressed data in a container is untrusted input, and gzip, Brotli and Zstd all expand zeroes by a factor of a thousand or more, so without a ceiling a small crafted file decides how much memory the process asks for. The ceiling is far above anything the formats produce in practice — the largest blob VersaTiles decompresses in one call is a .versatiles block index, under a megabyte — so raise it only if a legitimate input hits it.
• VERSATILES_MAX_HTTP_BODY_BYTES - Ceiling on a whole HTTP response body read from a remote source, in bytes (default 268435456 = 256 MiB). Applies to reads that fetch an entire document — a remote .vpl, a TileJSON, a file served from a remote static folder — where nothing in the request says how much to expect. Range reads are not covered by it: they are bounded by the range they asked for, and a response carrying a different number of bytes is refused regardless of this setting.

Memory for writing .versatiles containers:

• VERSATILES_WRITE_TILE_BUFFER - Number of compressed tiles buffered between the parallel compressor and the serial writer (default 64). Tiles are streamed straight to the output, so peak writer memory is ≈ this × the tile size — independent of how large a block is. Lower it for very large tiles on memory-constrained machines, or raise it for more write-ahead.

Example usage:

# In one line
VERSATILES_CACHE_DIR=/var/cache/versatiles versatiles serve tiles.versatiles

# or
export VERSATILES_CACHE_DIR=/tmp/versatiles_cache
versatiles serve https://download.versatiles.org/osm.versatiles

versatiles supports GDAL since v1.0.0. However, this is still experimental.

If you require GDAL support:

1. Install GDAL via your system package manager: ./scripts/install-gdal.sh (Supports Debian/Ubuntu, Alpine, and macOS via Homebrew)
2. Build with the gdal feature: cargo build -F gdal --release

VersaTiles is built with Rust and includes Node.js bindings (NAPI-RS).

Required:

• Rust 1.95+ (installation)
• Node.js 22.12+ (for Node.js bindings)

Optional:

• Lefthook - Pre-commit hooks
• GDAL 3.x - For GDAL support (build instructions)

# Clone repository
git clone https://github.com/versatiles-org/versatiles-rs.git
cd versatiles-rs

# Build debug version
cargo build --bin versatiles

# Run tests
cargo test

# Run binary
./target/debug/versatiles --version

Verify code quality before committing:

./scripts/check.sh

This runs:

• Rust: formatting (rustfmt), linting (clippy), type-checking, tests, doc tests
• Node.js: formatting (Prettier), linting (ESLint), type-checking (TypeScript), tests (Vitest)

Rust:

# Auto-format
cargo fmt-all

# Auto-fix clippy warnings
cargo clippy --fix

# Run specific tests
cargo test raster_overscale
cargo test --package versatiles_pipeline

Node.js:

cd versatiles_node

# Auto-fix all issues
npm run fix

# Individual tasks
npm run format        # Prettier
npm run lint:fix      # ESLint auto-fix
npm run typecheck     # TypeScript check
npm test              # Vitest

Debug build (fast compilation, slow execution):

cargo build --bin versatiles
# Output: ./target/debug/versatiles

Release build (slow compilation, fast execution):

cargo build --bin versatiles --release
# Output: ./target/release/versatiles

With GDAL support:

# Install GDAL (via system package manager)
./scripts/install-gdal.sh

# Build with GDAL feature
cargo build --bin versatiles --release -F gdal

# All tests
cargo test

# Specific package
cargo test --package versatiles_core
cargo test --package versatiles_pipeline

# Specific test
cargo test raster_overscale

# With output
cargo test -- --nocapture

# Ignored tests (long-running)
cargo test -- --ignored

# Generate docs
cargo doc --no-deps --open

# Test docs
cargo test --doc

Install Lefthook for automatic quality checks:

# macOS
brew install lefthook

# Linux
curl -fsSL https://raw.githubusercontent.com/evilmartians/lefthook/main/install.sh | sh

# Windows
scoop install lefthook

# Enable hooks
lefthook install

Hook behavior:

• pre-commit: Fast checks (formatting, basic linting)
• pre-push: Full checks (all tests, clippy, type-checking)

Skip hooks when needed:

# Skip pre-commit
LEFTHOOK=0 git commit -m "message"

# Skip pre-push
git push --no-verify

See versatiles_node/CONTRIBUTING.md for detailed workflow.

Quick reference:

cd versatiles_node

# Install dependencies
npm install

# Build Rust bindings
npm run build

# Build debug (faster compilation)
npm run build:debug

# Run tests
npm test

# Full check before commit
npm run check

We welcome contributions! Please:

1. Fork and create a feature branch:

   git checkout -b feature/my-feature

2. Make changes and test:

   ./scripts/check.sh

3. Commit with clear messages:

   git commit -m "feat: add new feature"

4. Push and create pull request:

   git push origin feature/my-feature

Commit message format:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Formatting, no code change
• refactor: Code restructuring
• test: Adding tests
• chore: Maintenance tasks

• /versatiles/ - Main library and binary
• /versatiles_container/ - Handles tile containers (*.versatiles, *.mbtiles, *.pmtiles, etc.)
• /versatiles_core/ - Core data types and utilities
• /versatiles_derive/ - Derive macros for the library
• /versatiles_geometry/ - Handles geometric data (OSM, GeoJSON, vector tiles, etc.)
• /versatiles_image/ - Manages image data (PNG, JPEG, WEBP)
• /versatiles_pipeline/ - VersaTiles Pipeline for efficient tile processing

Dependencies of the versatiles packages:

---
config:
  layout: elk
---
flowchart TB
    versatiles --> versatiles_container
    versatiles --> versatiles_core
    versatiles --> versatiles_derive
    versatiles --> versatiles_geometry
    versatiles --> versatiles_image
    versatiles --> versatiles_pipeline
    versatiles_container --> versatiles_core
    versatiles_container --> versatiles_derive
    versatiles_container --> versatiles_geometry
    versatiles_container --> versatiles_image
    versatiles_core --> versatiles_derive
    versatiles_geometry --> versatiles_core
    versatiles_geometry --> versatiles_derive
    versatiles_image --> versatiles_core
    versatiles_image --> versatiles_derive
    versatiles_node --> versatiles
    versatiles_node --> versatiles_container
    versatiles_node --> versatiles_core
    versatiles_node --> versatiles_geometry
    versatiles_pipeline --> versatiles_container
    versatiles_pipeline --> versatiles_core
    versatiles_pipeline --> versatiles_derive
    versatiles_pipeline --> versatiles_geometry
    versatiles_pipeline --> versatiles_image

• /docker/ - Dockerfile for Linux builds
• /testdata/ - Test files for validation
• /scripts/ - Development and CI/CD automation scripts — see scripts/README.md for the full reference. Most commonly used: check.sh, build-release-with-gdal.sh.

VersaTiles can be used as a command-line tool or integrated into Rust projects as a library. Check out crates.io and docs.rs for more details.

For advanced usage, guides, and detailed documentation, visit the official documentation.

See RELEASING.md for the complete release process.

Quick version:

# Interactive mode - select release type from menu
./scripts/release-package.sh

# Or use command-line argument
./scripts/release-package.sh patch  # or minor/major/alpha/beta/rc/dev

# Push to trigger automated release
git push origin main --follow-tags

The GitHub Actions workflow will automatically:

• Build CLI binaries for 8 platforms (Linux gnu/musl x64/arm64, macOS x64/arm64, Windows x64/arm64)
• Build NAPI-RS bindings for Node.js (8 platform-specific packages)
• Publish to npmjs.com (@versatiles/versatiles-rs + 8 platform-specific packages)
• Create GitHub release with CLI binaries
• Trigger Docker and Homebrew updates

VersaTiles is actively developed, and contributions are welcome! If you find bugs, need features, or want to contribute, please check the GitHub repository and submit an issue or pull request.

This project is licensed under the MIT License. See the LICENSE file for details.