Posted by & filed under QGIS.

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 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!

  • Pingback: QGIS Mapserver – QGIS goes Server! « Free and Open Source GIS ramblings

  • pka

    It is also possible to add the QGIS project with a map parameter similar to UMN mapserver. And for Ubuntu users who don’t want to compile QGIS, a binary package is available on

    • Tim Sutton

      Ah great extra tips! Thanks Pirmin!

  • Pingback: GIS-Lab Blog» Архив блога » Новости вокруг 56

  • Pingback: GIS-Lab Blog» Архив блога » QGIS 1.6 ‘Copiapó’

  • Pingback: Quantum GIS News: Updated To Version 1.6, Python qGIS Cookbook Released

  • Pingback: Quantum GIS資源網@Sinica » QGIS推出1.6.0版 ‘Copiapó’

  • samtux

    Thanks Tim for this great information.

    Can I install QGIS Server on Windows too?

    • Tim Sutton


      I believe so yes. There are packages in the OSGEO4W installer. I haven’t tried it myself….



      • Wernher

        I tried to install qgis_mapserv.fcgi.exe on windows xp:

        (via osgeo4w \OSGeo4W\apps\qgis\bin\qgis_mapserv.fcgi.exe)

        So I changed the httpd.conf of the apache and added :

        ScriptAlias /qgis-bin/ “c:\OSGeo4W/apps/qgis/bin/”

        AllowOverride None
        Options +ExecCGI -MultiViews +SymLinksIfOwnerMatch
        Order allow,deny
        Allow from all
        # Next for QGIS Mapserver
        SetEnv LD_LIBRARY_PATH “c:\OSGeo4W/apps/qgis/bin/”
        SetEnv PATH “c:\OSGeo4W/apps/qgis/bin/”

        but now the apache throws an error:
        “Premature end of script headers: qgis_mapserv.fcgi.exe”
        Whats wrong ?

  • till

    QGIS Server on Windows – HOWTO

    0. Pre-notes
    Working on/in windows means for me like working with ten thumbs on two left hands — or:
    I am not a windows expert! And normally I even do not have easy access to any winbox. So this howto explains
    how I got QGIS server up and running but might not always show the ideal way.

    If I placed something in “[]” this means that you have to use this as a variable and replace this by your specific keywords.

    Please also read the notes on QGIS server here:

    So, let’s start….

    1. Download the OsGeo4W-Installer

    2. Execute the installer, use the settings below:
    (maybe the wording differs a little bit, as I tranlated this from german, I do not have an english winbox for testing, so I didn’t see the english naming used by the installer)
    -> advanced installation (3. possibility)
    -> install from web (1. possibility)
    -> root-directory c:\OSGeo4W, all users
    -> leave the local-package directory as is or change it
    -> choose web-access due to your lan
    -> choose the following packages (don’t care about dependencies, the installer does this automatically):
    – Desktop: Qgis
    – Web: Apache Webserver

    3. In the moment (july 2011) QGIS on windows seems not to work as FastCGI, so edit the file

    In this section:

    SetHandler fcgid-script
    Options ExecCGI
    Order allow,deny
    Allow from all

    change the SetHandler to this:

    #SetHandler fcgid-script
    SetHandler cgi-script

    Restart apache (e.g. settings-panel -> services -> apache -> restart)

    3b. If you do not want to use the osgeo-apache and already have your own apache running, just create a directory in the apache-dir, e.g.
    “apache/httpd.d/” and copy the httpd_qgis.conf file into this directory, then add this section to the httpd.conf of your apache.
    Placethis at the end of the config-file and ensure bot to be in any subsection (subsections appear like this and end with

    # parse other apache conf files
    include “C:\[YOURPATHTOYOURAPACHEINSTALLATION]\httpd.d\httpd_*.conf”

    Restart apache (e.g. settings-panel -> services -> apache -> restart)

    You also might change the installation directory of the QGIS server by editing the pathes in the httpd_qgis.conf-file. Always restart Apache after changing anything on the apache-config
    (or restart your complete server as you might be used to ;-) )

    4. In my installation the link to the required *.dll’s did not work. There are required *.dlls in the folder


    I copied all *.dll’s from there to my qgis-server folder:


    I am sure there is a better way, either linking the *.dll’s to apache OR copy them to the c:/windows/system32/ directory,
    but as I am not a windows expert, I choosed the quick&dirty way, which also works.

    I also tried to find the really used dll’s by double-clicking on the qgis_mapserv.fcgi.exe, but this is awful as these are many.

    5. Create a QGIS project (e.g. world.qgs), save it e.g. to “c:/myprojects/” and call the GetCapabilities document by sending this request through your browser:


    A capabilities-XML should appear. If so, congratulations, try your new QGIS server by calling a getMap-request:


    Be sure to have your correct layername(s) in the “&LAYER=[YOURLAYERNAME]“-Tag in the URL above.
    You’ll find them in the capabilities in the subsection in the subtag [YOURLAYERNAME] – please use the not the title!

    Now you are ready to go. In the following I explain howto update and give some more notes from my experience.

    6. Update QGIS-Server to nightly-built

    In order to get the newest QGIS-builts also use the osgeo4w installer. First backup your httpd_qgis.conf-file, then run the osgeo4w-setup.exe again.
    In the desktop-section now choose “QGIS nightly builts” (yes, Desktop – they include also the newest qgis_mapserv.fcgi.exe!!)

    Go ahead as described in top 1.

    Afterwards you’ll probably have a new qgis-setup. In the source-files you’ll find the brand new qgis_mapserv.fcgi.exe in the qgis-binary folder.
    Copy this to the c:/osgeo4w/apps/qgis/bin-directory and test. I do not know, if probably any of the dll-files have changed, so if this does not work,
    you might copy the dll’s again as discussed above in top 4.

    7. some notes
    – avoid blanks in any names (project-files) and names of layers (not the titles!) as this is transported via URL and might cause problems
    – in my experience it doesn’t matter whether you use “/” or “\” in paths, except the following point:
    – if data and/or project files are on a network-directory, which is mounted as e.g. disk “r:\” under windows, change the access to the Uniform Naming Convention (UNC)
    (see also: Uniform_Naming_Convention)
    which e.g. leads from “r:\[YOURPATH]\” to “\\[YOURINTERNALSERVERID]\[YOURPATH]”

    You might change this by search and replace directly in the *.qgs-file or by replacing it in the QGIS gui when adding a layer.
    QGIS will accept this pathes as well and will not change this when re-opening the project.

    8. Have fun and please report comments on this HowTo and on QGIS Server!

    • Tim Sutton

      Thanks for the great how-to Till!



  • till

    Comment from somebody who used this tutorial (06.09.2011):

    > Hallo,
    > thanks for the nice QGIS Server tutorial (!
    > I configured QGIS Server under Windows, but in contrast to step 4 of the tutorial I had to copy all *.dlls from the C:\OSGeo4W\bin directory (not from C:\OSGeo4W\apache\bin) so that it worked. Before that, I had to install the “fcgi: Fast CGI Library” from the OSGeo4W setup, because these *.dlls were missing as well. Maybe you can add/change this in your tutorial.

  • Pingback: Norwegian Trekking with QGIS Server « Linfiniti Geo Blog

  • Jose


    anyone know how to run QGisServer with Nginx?

    Best Regards

  • rob

    Hi Jose and All,

    Did you ever manage to get qgis-mapserver working with Nginx? I’ve tried a few methods myself to no avail.

    1) qgis_mapserv.fcgi under uwsgi, passing requests via the nginx uwsgi plugin.

    2) qgis_mapserv.fcgi under supervisord, passing requests via fastcgi plugin.

    The second setup I can manage to get the default qgis-mapserver error page but I can’t pass any arguments. e.g.