This tutorial guides you to the MapProxy installation process.

This tutorial was created and tested with Debian 5.0, if you’re installing MapProxy on a different system you might need to change some package names.

MapProxy is registered at the Python Package Index (PyPI). If you have installed Python setuptools (python-setuptools on Debian) you can install MapProxy with sudo easy_install MapProxy. This is really easy but we recommend to not use this method.

We highly advise you to install MapProxy into a virtual Python environment. Read about virtualenv if you want to now more about the benefits.

Create a new virtual environment

If you don’t have virtualenv installed, you can download a self-contained version:


Next we create a new virtual environment for our proxy installation. It is a good idea to organize all your environments into a single directory. I use ~/venv for that. To create a new environment with the name mapproxy and to activate it call:

python --distribute ~/venv/mapproxy
source ~/venv/mapproxy/bin/activate


The last step is required every time you start working with your MapProxy installation.

Install MapProxy


To install MapProxy you need

  • Mercurial
  • C compiler
  • Python (development tools)

MapProxy uses the Python Image Library (PIL). To get full support for JPEG and PNG images and attribution/watermarks you will need the following libraries:

  • libjpeg
  • zlib
  • libfreetype

To install all requirements on Debian or Ubuntu call:

sudo aptitude install mercurial build-essential python-dev \
    libjpeg-dev libz-dev libfreetype6-dev


Your virtual environment should already contain pip, a tool to install Python packages. If not, easy_install pip is enough to get it. We have put a requirements file online that describes which Python packages are needed for MapProxy and where to get these.

To install MapProxy and all dependencies, call the following:

pip install -r

If you install MapProxy on Windows you should install the required packages manually with easy_install and not with pip. easy_install will download and install binary packages on Windows so you do not need a compiler.

To check if the MapProxy was successfully installed you can directly call the version module. You should see the installed version number.

python -m mapproxy.core.version

Create a configuration

To create a new set of configuration files for MapProxy call:

paster create -t mapproxy_conf mymapproxy

This will create a mymapproxy directory with an etc, var and tmp directory. The etc directory contains all configuration files. Refer to the configuration documentation for more information. With the default configuration all log files and the cached data will be placed in the var directory.

Start the test server

To start a test server:

cd mymapproxy
paster serve etc/develop.ini --reload

There is already a test layer configured that obtains data from the Omniscale OpenStreetMap WMS. Feel free to use this service for testing.

You can now issue you first request to the MapProxy: http://localhost:8080/service? The capabilities document is at: http://localhost:8080/service?SERVICE=WMS&VERSION=1.1.1&REQUEST=GetCapabilities

Table Of Contents

Previous topic

MapProxy Documentation

Next topic


This Page