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
  • Building with Cargo
  • Building from Source
• Quick Start
• Usage
  • Core Concepts
  • Commands
  • VersaTiles Pipeline Language
• Configuration
• GDAL support
• Development
  • Prerequisites
  • Quick Start
  • Development Workflow
  • Pre-commit Hooks (Recommended)
  • Node.js Bindings Development
  • Release Process
  • Contributing
• Repository Structure
• Using as a Library
• Additional Information
• Contributing
• License

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

curl -Ls "https://github.com/versatiles-org/versatiles-rs/raw/main/scripts/install-unix.sh" | sudo sh

Install VersaTiles via Homebrew:

brew tap 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-org/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/

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:

• .versatiles - Native format (best compression, fastest access)
• .mbtiles - SQLite-based (widely compatible)
• .pmtiles - Cloud-optimized single-file format
• .tar - Simple archive format
• Directories - Folder structure: z/x/y.ext

Remote access: VersaTiles can read remote .versatiles and .pmtiles files via HTTPS:

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

Run versatiles to see available commands:

Usage: versatiles [OPTIONS] <COMMAND>

Commands:
  convert  Convert between different tile containers
  probe    Show information about a tile container
  serve    Serve tiles via HTTP
  dev      Developer tools (unstable)
  help     Show detailed help

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

Basic conversion:

versatiles convert input.mbtiles output.versatiles

Advanced options:

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

Analyze tile containers to understand their contents and structure.

Basic usage:

versatiles probe tiles.versatiles

Depth levels:

Examples:

# Quick metadata check
versatiles probe tiles.versatiles -d

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

# Deep inspection with tile statistics
versatiles probe tiles.versatiles -ddd

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

Run a local or production tile server with advanced configuration.

Basic usage:

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

Server options:

Custom tile IDs:

Assign custom IDs to tile sources using bracket or hash syntax:

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

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

# Hash syntax: source#id
versatiles serve tiles.versatiles#osm

Access tiles at: http://localhost:8080/{id}/{z}/{x}/{y}.{ext}

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, directories

Remote serving:

# 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

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

# 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"
]

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

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 domain
    - "*.dev.example.org"            # Subdomain wildcard
    - "https://example.*"            # TLD wildcard
    - "/^https://.*\\.example\\.org$/" # Regex pattern
  max_age_seconds: 86400

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

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/{name}/{z}/{x}/{y}.{ext}

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

server:
  ip: 0.0.0.0
  port: 8080
  minimal_recompression: false

cors:
  allowed_origins:
    - "https://myapp.com"
    - "*.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

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

Due to the numerous combinations of operating systems, package managers and GDAL versions, we must streamline this ecosystem. If you require GDAL support, we recommend the following:

1. Build GDAL locally by running ./scripts/install-gdal.sh. This will build and install GDAL in the subfolder ./.toolchain/gdal
2. Build versatiles with the features gdal. We recommend using the scripts ./scripts/build_debug.sh and ./scripts/build_release.sh.

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

Required:

• Rust 1.92+ (installation)
• Node.js 20+ (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

# 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:

# Build GDAL first
./scripts/install-gdal.sh

# Build with GDAL features
./scripts/build_release.sh

# 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_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:

Most commonly used: check.sh, build-release.sh, release-package.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.