Date Mon 23 August 2010

Update 11 June 2011:I have updated this article to call what was previously referred to as 'QGIS Mapserver' by its new official name: QGIS Server. The name was changed to prevent confusion with the UMN Mapserver product.

Marco Hugentobler recently included his QGIS WMS Server work into QGIS trunk. You may have noticed QGIS being mentioned in Paul Ramsey's post about the WMS Shootout at OSGEO2010 and thought to yourself "huh? whats that?". Well let me introduce you....

The QGIS mapserver project implements a WMS server on top of the QGIS
libraries (funded by the EU projects Orchestra, Sany and the city of Uster).
  • Marco Hugentobler


You need to be using QGIS Trunk (or a nightly build with OSGEO4W for Windows users). On my Linux system I needed to install the fast cgi dev files:

sudo apt-get install libfcgi-dev

Then just recompile and install QGIS. After its built you will find a new item in the bin dir. On my system I build QGIS into ~/apps so my QGIS Server binary was here:



Since I build my QGIS into a non system dir, I had to tell apache about the library path for my CGI. Something like this:

ScriptAlias /cgi-bin/ /usr/lib/cgi-bin/
<Directory "/usr/lib/cgi-bin">
  AllowOverride None
  Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
  Order allow,deny
  Allow from all
  # Next for QGIS Mapserver
  SetEnv LD_LIBRARY_PATH /home/timlinux/apps/lib

Next I went to the cgi bin dir:

cd /usr/lib/cgi-bin/

And then I made a project directory. The rule is: one directory per QGIS project you want to serve.

sudo mkdir world
cd world

Next I linked in the qgis cgi:

sudo ln -s /home/timlinux/apps/bin/qgis_mapserv.fcgi .

and then copied in the project file:

sudo cp /home/timlinux/gisdata/QGISProjects/world.qgs .

Symlinking of the project file may work for you - check your apache configs to allow symlinking I guess.

One other thing to do is copy the capabilities document into the world directory. Actually the server still works without it but we want to be neat & tidy right?

sudo cp /home/timlinux/dev/cpp/qgis/src/mapserver/wms_metadata.xml .

Now edit that file and set your details as appopriate.

I guess you are waiting to carry on with the next 25 pages of configuration instructions....right? Wrong! Thats all you need to do!


First you want to make a nice QGIS project and save the .qgs file in the project directory as outlined above. Here is what my QGIS project looked like:


To test you can point your web browser at your server:


Which makes a capabilities doc something like this:


And how about a nice map?


Which produced this:


And just to be really meta, lets load the WMS source back into QGIS from where it started!


You see the map renders exactly the same as our original project - marvelous!

Things to note

  • The project should use [STRIKEOUT:relative] absolute paths (see project properties dialog)...or better yet load your data into PostGIS and forget shapefiles.
  • Dont forget to copy over your capabilities document and edit it with appropriate details
  • This is not a 'robotosed' GUI ala early versions of ArcIMS which took over your desktop application. Its a full 'headless' cgi web service.
  • You can use all the nice new symbology and labelling features of QGIS to make top quality maps

Thanks to Marco (and those who sponsored him)!

Addendum to notes added Aug 23, 11:17pm (provided by Andreas Neuman)

* QGIS Mapserver (or however it will be called) implements WMS 1.3 only (not WMS 1.1.1)
* GetFeatureInfo should support: text, html, xml
* GetFeatureInfo honors some of the attribute settings of a QGIS layer: hidden attributes are suppressed, column aliases are used if present.
* When doing the GetCapabilities, the answer can be very slow and big, because for every layer, QGIS will return all available CRS. You can limit this list by using adding the following XML elements to the properties section:
<WMSEpsgList type="QStringList">

QGIS will not remove these settings from the .qgs file after saving it from the desktop version, but currently there is no GUI to do the WMS settings.

* By default, QGIS Mapserver will advertise the maximum extent of all involved layers. This can be overridden by the following setting, again in the section of a .qgs file; replace with your own min/max settings:

<WMSExtent type="QStringList">

* GetLegendGraphics should work, e.g.


* QGIS Mapserver can handle multiple project files with one fcgi binary. On a first request of a newly started Apache server, the request will be slower, because the .qgs file has to be parsed, later requests are fast, because there is a cache for more .qgs files. You can use the "map=/home/path/to/your/project.qgs" parameter to specify which project you want to access.

It would be nice if we could expose some of the "hidden" WMS properties in a GUI, somewhere in the QGIS project properties. Maybe a Server-Settings tab.

Thanks for the additional comments Andreas!


comments powered by Disqus