How to Host and Test PMTiles on GitHub Pages — The Easiest Way to Serve Maps Without a Server
Ronit Jadhav

Ronit Jadhav @ronitjadhav

Location:
Berlin
Joined:
Jun 30, 2024

How to Host and Test PMTiles on GitHub Pages — The Easiest Way to Serve Maps Without a Server

Publish Date: May 29
0 0

Do you want to share your own tiled map (like city boundaries or custom vector data) without paying for hosting or running a server?

You can host .pmtiles files (Protomaps tile archives) entirely on GitHub Pages and consume them using OpenLayers. This post shows how to:

  • Get your .pmtiles data
  • Host it on GitHub Pages (completely free!)
  • Build simple viewers to display your maps
  • Test everything instantly in your browser

🧭 What is PMTiles?

PMTiles is a single-file format for storing map tiles. Instead of hundreds of folders like /z/x/y.mvt, you get one file, which:

  • Contains an internal index
  • Can be read using HTTP range requests
  • Works perfectly on static hosts like GitHub Pages

🔥 Live Demos

🧪 Test any PMTiles file

Try pasting any PMTiles URL into this live app:

🔗 maps.protomaps.com

You can:

  • Load tiles from a URL
  • Drag & drop your local .pmtiles
  • Reset to original map

🧱 How to Get PMTiles Data

Need your own PMTiles data? You have a few options:

🚀 Quick Start: For detailed instructions on downloading and extracting PMTiles data from OpenStreetMap, check out the official guide:

🔗 Protomaps Getting Started Guide

⚡ Or try these ready-made sources:

  • Pre-built regional extracts at maps.protomaps.com/builds
  • Create custom extracts using the PMTiles CLI
  • Use existing PMTiles files from the community

Once you have your .pmtiles file, you're ready to host and visualize it!

🛠️ Hosting PMTiles on GitHub Pages

GitHub Pages is great for PMTiles testing and exploration:

  • ✅ Free static hosting
  • ✅ Supports byte-range requests (required by .pmtiles)
  • ✅ Global CDN
  • ✅ No backend needed

⚠️ Important Note

GitHub Pages is recommended for testing, prototyping, and personal projects only. For production applications with high traffic or performance requirements, consider dedicated hosting solutions. GitHub Pages has bandwidth limitations and may experience slower response times under heavy load.

🚀 Host Your PMTiles on GitHub Pages

The approach depends on your file size. GitHub has different limits for web uploads vs. Git pushes.

📏 File Size Considerations

Small Files (< 25MB):

  • Can be uploaded directly through GitHub's web interface
  • Simple drag-and-drop workflow

Large Files (25MB - 100MB):

  • Must use Git command line or GitHub Desktop
  • Standard Git push works fine

Very Large Files (> 100MB):

  • Not recommended for GitHub Pages
  • Consider alternative hosting solutions for better performance

Method 1: Small Files (< 25MB) - Web Upload

  1. Create a new repository on GitHub (e.g. my-city-map)
  2. Upload your PMTiles file:
    • Just drag and drop your_map.pmtiles into the repo
    • No HTML, no code - just the data file!
  3. Enable GitHub Pages:
    • Go to Settings → Pages
    • Choose Source: Deploy from a branch
    • Branch: main
    • Folder: / (root)
    • Click Save

Method 2: Large Files (25MB - 100MB) - Git Command Line

For files between 25MB and 100MB, you'll need to use Git locally:

  1. Create repository on GitHub (e.g. my-city-map)

  2. Clone and add your file locally:

   # Clone the empty repository
   git clone https://github.com/YOUR_USERNAME/my-city-map.git
   cd my-city-map

   # Copy your PMTiles file into the directory
   cp /path/to/your_map.pmtiles .

   # Add and commit the file
   git add your_map.pmtiles
   git commit -m "Add PMTiles data"

   # Push to GitHub
   git push origin main
Enter fullscreen mode Exit fullscreen mode
  1. Enable GitHub Pages:
    • Go to Settings → Pages in your GitHub repo
    • Choose Source: Deploy from a branch
    • Branch: main, Folder: / (root)
    • Click Save

🌐 Your PMTiles URL

Regardless of the method used, your hosted PMTiles file will be available at:

https://YOUR_USERNAME.github.io/REPO_NAME/your_map.pmtiles
Enter fullscreen mode Exit fullscreen mode

For example: https://johndoe.github.io/my-city-map/berlin_area.pmtiles

🧪 Test Your Map Instantly

Copy your PMTiles URL and paste it into:

🔗 maps.protomaps.com

🎉 Boom! Your map loads instantly - no coding required!

💡 Pro Tips

  • File naming: Use descriptive names like berlin_districts.pmtiles instead of map.pmtiles
  • Repository organization: Keep related files together (multiple zoom levels, different regions)
  • File size: Keep files under 100MB for optimal GitHub Pages performance
  • Compression: PMTiles files are already compressed, but consider the geographic scope to optimize size
  • Performance: For production use, consider dedicated hosting services for better performance and reliability
  • GitHub limits: Be aware of GitHub Pages' soft bandwidth limit (100GB/month) and response time limitations

🛠️ Want to Build Custom Viewers?

For developers who want to integrate PMTiles into their own applications:

These libraries make it easy to consume PMTiles in web applications with full styling and interactivity control.

📚 More Resources

❤️ Final Thoughts

PMTiles + GitHub Pages = the simplest way to test and explore interactive maps:

  • 📁 Just one file to manage
  • 🆓 Completely free hosting (with generous limits)
  • ⚡ Good performance for development and testing
  • 🚀 Deploy in under 5 minutes
  • 📈 Scales from small city maps to country-wide datasets

Perfect for personal projects, prototyping, city maps, data visualizations, or learning. No servers, no complexity, minimal costs.

For production applications: Consider dedicated hosting solutions for optimal performance and reliability.

🗺️ Happy mapping!

Comments 0 total

    Add comment