OpenStreetMap: Tile Server and Cache with MapProxy

First published — Nov 18, 2023
Last updated — Apr 30, 2024

Computer cartography. OpenStreetMap (OSM), MapProxy. WMS, WMTS, Slippy, TMS, KML. Custom tile proxy and cache.

Article Collection

This article is part of the following series:

1. Osm

Table of Contents


All components of OpenStreetMap exist as Free Software and can be self-hosted and customized.

When setting up a custom or self-hosted solution, it is probably easiest to replace components from the top down, i.e. starting with the viewer and ending with the tile server.

This article explains how to easily set up MapProxy to enable interoperability between different applications, cache results, and optionally even reproject tiles.


MapProxy was originally developed by a German company Omniscale.

Its homepage is at and the code is at


MapProxy is very easy to set up. The complete documentation can be found at, but in general, the following should be enough to install MapProxy:

apt install python3-{pip,pyproj}

pip3 install MapProxy


MapProxy comes with utility functions that create example configs.

To produce a basic config, run:

~/.local/bin/mapproxy-util create -t base-config mymapproxy

mymapproxy is the name of directory which will be created if missing, and the configuration files will be saved to it.

After generation, the contents will look like this:

ls mymapproxy/


One file necessary to run the server is mapproxy.yaml. Files named full_* are generated by mapproxy for reference.

Omniscale provides an OSM tile server and the default configuration uses it. It does not allow unrestricted access without registration, and an appropriate message about it in English and German shows on the map:

Thank you for using our OpenStreetMap WMS demo!

Please sign up at for unrestricted access.

However, that is quite OK to verify our setup!


To start MapProxy, run:

cd mymapproxy/

~/.local/bin/mapproxy-util serve-develop mapproxy.yaml

Once MapProxy starts, it automatically initializes the following endpoints for different protocols:

Leaflet Map

In OpenStreetMap: Custom Web Map Viewer with Leaflet we have set up a custom HTML page that displays OpenStreetMap map.

We can easily extend the map’s configuration to include an additional data source, the Slippy map coming from MapProxy:

The map.html patch file is very simple:

--- map.html	2024-04-30 18:18:20.564000000 +0000
+++ map.html	2024-04-30 18:34:42.944000000 +0000
@@ -46,9 +46,14 @@
         maxZoom: 19,
         attribution: '&copy; <a href="">OpenStreetMap</a> contributors, &copy; <a href="">CARTO</a>'
+      var mapProxy = L.tileLayer('http://localhost:8080/tiles/osm/webmercator/{z}/{x}/{y}.png', {
+        maxZoom: 19,
+        attribution: '&copy; <a href="">Omniscale GmbH & Co. KG</a>'
+      });
       var baseMaps = {
         "CARTO.Positron": positron,
         "<span style='color: red'>OpenStreetMap.HOT</span>": osmHOT,
+        "MapProxy": mapProxy,
         "OpenStreetMap": osm,
@@ -63,7 +68,7 @@
       // Create map - position it at specified latitude/longitude (0,0) and with a given zoom level (0-19)
-      var map ='map', { minZoom: 0, maxZoom: 19, layers: [positron, osmHOT, osm] }).setView({lat: 0, lon: 3}, 5); //.fitWorld();
+      var map ='map', { minZoom: 0, maxZoom: 19, layers: [mapProxy, positron, osmHOT, osm] }).setView({lat: 0, lon: 3}, 5); //.fitWorld();
       var layerControl = L.control.layers(baseMaps, overlayMaps).addTo(map);


Full content of the map file or a preview of the above page can be seen in map.html.

Note that MapProxy layer on the map will not show data unless you have actually installed MapProxy as per above instructions.

Article Collection

This article is part of the following series:

1. Osm

Automatic Links

The following links appear in the article:

1. OpenStreetMap: Custom Web Map Viewer With Leaflet - /osm-cartography-web-viewer/
2. http://localhost:8080/demo
3. http://localhost:8080/kml/osm/webmercator
4. http://localhost:8080/service?REQUEST=GetCapabilities
5. http://localhost:8080/tiles/osm/webmercator/0/0/0.png
6. http://localhost:8080/tms/1.0.0/osm/webmercator/0/0/0.png
7. http://localhost:8080/wmts/1.0.0/WMTSCapabilities.xml
8. http://localhost:8080/wmts/osm/webmercator/0/0/0.png
12. Omniscale -
13. MapProxy -
14. Map.html Patch File - map.html.patch