Py-qgis-server is a asynchronous HTTP Qgis server written in python on top of the tornado framework and the 0MQ messaging framework for distributing requests workers.

It is based on the new Qgis 3 server API for efficiently passing requests/responses using 0MQ messaging framework to workers.

The server may be run as a self-contained single service or as a proxy server with an arbitrary number of workers running remotely or locally. Independent workers connect automatically to the front-end proxy with no need of special configuration on the proxy side. Thus, this is ideal for auto-scaling configuration for use with container orchestrator as Rancher, Swarm or Kubernetes.

The server is aimed at solving some real situations encountered in production environment: zero conf scalability, handle long-running request situation, auto restart…


  • Multiples workers
  • Fair queuing request dispatching
  • Timeout for long running/stalled requests
  • Full support of qgis server plugins
  • Auto-restart trigger for workers
  • Support streamed/chunked responses
  • SSL support


  • OS: Unix/Posix variants (Linux or OSX) (Windows not officially supported)
  • Python >= 3.5
  • QGIS >= 3.10 installed
  • libzmq >= 4.0.1 and pyzmq >= 17


Install from source

  • Install from

    pip install py-qgis-server
  • Install from sources:

    pip install -e .
  • Install from build version X.Y.Z:

    make dist
    pip install py-qgis-server-X.Y.Z.tar.gz

Running the server

The server does not run as a daemon by itself, there is several way to run a command as a daemon.

For example:


qgisserver [options]


-d, --debug

Force debug mode. This is the same as setting the LOGGING_LEVEL option to DEBUG

-c, --config path

Use the configuration file located at path


Run only as proxy.

Running proxy and workers separately

If the --proxy option is set the server will act as a proxy server to talk to independent qgis workers.

QGIS workers can be run using the command:

qgisserver-worker [options]

The options are the same as

Running with Docker

Docker image is available on docker-hub.

All options are passed with environment variables. See the Configuration settings for a description of the options.

Install server plugins with the Docker container

The docker image is shipped with the qgis-plugin-manager.

To install or manage your server plugins, use the docker exec command into your container, the plugins will install in the folder defined by the SERVER_PLUGINPATH option.


docker exec myserver -it qgis-plugin-manager install "Lizmap server"

Running with Supervisor

Example of Supervisor configuration file for py-qgis-server /etc/supervisor/conf.d/py-qgis-server.conf:

command=/path/to/qgisserver -c /path/to/py-qgis-server-config-file.conf

Feel free to adapt environment variables depending on your setup and needs.

Once supervisor configuration file for py-qgis-server is created, py-qgis-server can be started using following commands:

sudo supervisorctl reread && sudo supervisorctl start py-qgis-server