OpenStreetMap: Tile Server and Cache with MapProxy

First published — Nov 18, 2023
Last updated — Nov 18, 2023

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. OpenStreetMap

Table of Contents


As mentioned in Introduction to OpenStreetMap and Computer Cartography , 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 you will need 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:

--- a/map.html	2023-11-25 18:52:46.948000000 +0000
+++ b/map.html	2023-11-25 18:52:26.220000000 +0000
@@ -45,10 +45,16 @@
       var positron = L.tileLayer('https://{s}{z}/{x}/{y}.png', {
         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 = {
         "OpenStreetMap": osm,
         "<span style='color: red'>OpenStreetMap.HOT</span>": osmHOT,
         "CARTO.Positron": positron,
+        "MapProxy": mapProxy,
       // Add one overlay layer showing some cities:
@@ -62,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: [osm, osmHOT, positron] }).setView({lat: 0, lon: 3}, 5); //.fitWorld();
+      var map ='map', { minZoom: 0, maxZoom: 19, layers: [osm, osmHOT, positron, mapProxy] }).setView({lat: 0, lon: 3}, 5); //.fitWorld();
       var layerControl = L.control.layers(baseMaps, overlayMaps).addTo(map);


Preview of the above page can be seen in map.html .

Note that MapProxy layer will not be visible unless you have an instance running locally.

Article Collection

This article is part of the following series:

1. OpenStreetMap

Automatic Links

The following links appear in the article:

2. OpenStreetMap: Custom Web Map Viewer With Leaflet - /osm-cartography-web-viewer/
3. Introduction to OpenStreetMap and Computer Cartography - /osm-cartography/
4. http://localhost:8080/demo
5. http://localhost:8080/kml/osm/webmercator
6. http://localhost:8080/service?REQUEST=GetCapabilities
7. http://localhost:8080/tiles/osm/webmercator/0/0/0.png
8. http://localhost:8080/tms/1.0.0/osm/webmercator/0/0/0.png
9. http://localhost:8080/wmts/1.0.0/WMTSCapabilities.xml
10. http://localhost:8080/wmts/osm/webmercator/0/0/0.png
14. Omniscale -
15. MapProxy -
16. map.html
17. Map.html Patch File - map.html.patch