« Previous - Version 5/40 (diff) - Next » - Current version
Marco Hugentobler, 01/16/2012 01:00 am

About QGIS Server

QGIS Server provides a web map service (WMS) using the same libraries as the Quantum GIS (QGIS) desktop application.
Maps and print templates created in QGIS desktop can be published as web maps simply by copying the QGIS project file into the server directory. The resulting web maps look exactly the same as in the desktop.
QGIS Server is usually run as CGI/FastCGI module within the Apache Webserver.

Core Features

  • Web Map Service (WMS) implementation
  • Built-in PDF output
  • WYSIWYG map creation with QGIS
  • Advanced cartographic symbolisation
  • Supports Styled Layer Descriptor (SLD)
  • Identification of features and display of attribute data

Webserver configuration

Debian/Ubuntu Linux

To setup QGIS Server with Apache 2 mod_fastcgi, the following packages are required:

apt-get install qgis-mapserver libapache2-mod-fcgid

Note that libapache2-mod-fcgid and libapache2-mod-fastcgi are different packages and require different configurations.

Using the default configuration, QGIS Server should answer a GetCapabilities request from here:


Mac OS X

QGIS Server uses the system Apache 2 with mod_fastcgi in a default configuration, on OS X 10.5 (Leopard) and above. The system Apache 1 on OS X 10.4 and below does not include mod_fastcgi or the fastcgi library needed to compile QGIS Server, and installing the library and module will not be covered here.

The QGIS Server fastcgi will be installed within the QGIS application package as QGIS.app/Contents/MacOS/fcgi-bin/qgis_mapserv.fcgi (note: this could change in the future). The following instructions assume a default installation in /Applications.

The method used depends on whether the mapserver is running on the standard client OS X ("OS X") or OS X Server.

A handy tool for both is TextWrangler, but you can use any text editor that can edit and save files that need administrator permissions.

Enable mod_fastcgi

On OS X, edit /etc/apache2/httpd.conf. Find the line starting with "#LoadModule fastcgi_module" (it may or may not have the leading "#"). Remove the "#" at the beginning of the line, if present. Save and close the file.

On OS X Server, use the Server Admin app. Select Web under your server, then Settings->Modules. Find fastcgi_module in the module list and check the box to enable it. Click the Save button.

You could also edit /etc/apache2/httpd.conf the same as for OS X, since the next can't be done from Server Admin.

Configure mod_fastcgi

On OS X, create a new text file /etc/apache2/other/qgis-mapserver.conf with the content:

<IfModule mod_fastcgi.c> 
  FastCgiConfig -appConnTimeout 60 -idle-timeout 60 -init-start-delay 1 -minProcesses 2 -maxClassProcesses 20 -startDelay 5
  AddHandler fastcgi-script .fcgi
  Alias /qgis-mapserv/ /Applications/QGIS.app/Contents/MacOS/fcgi-bin/
  <Directory /Applications/QGIS.app/Contents/MacOS/fcgi-bin/>
    AllowOverride None
    Options ExecCGI
    Order allow,deny
    Allow from all

If you already installed MapServer (the KyngChaos package includes a fastcgi configuration as of v5.6.5-2), then just add the lines above from "Alias" to "</Directory>" to /etc/apache2/other/mapserv_fcgi.conf.

For OS X Server, edit /etc/apache2/httpd.conf. Add the above configuration to the end of the file. Here also, if you have installed MapServer, there should be a mod_fastcgi block, so you just need to add the QGIS stuff to it. Save and close.

Restart Apache and Test

Restart the web server.

The simplest way on both OS X and OS X Server is to type in a Terminal:

 sudo apachectl graceful

Test by opening Safari and browsing to:


You should get a message "Configuration file problem". This is good, QGIS Server is running, but no map file was given.


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:

and 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

3a. Apache (2.2.14-4 from OSGeo4W) does not have any default IP/port set and it fails to start. Edit the file


and change
   Listen @apache_port_number@

to your needs, for example, to listen on port 80,use
   Listen 80

Start apache (e.g. settings-panel -> services -> apache -> start.
Now you should be able to open default Apache web page in web browser (using or http://localhost/ on local computer)

3b. In the moment (july 2011; this was not necessary with Apache 2.2.14-4 and QGIS Server 1.7.1-2 - October 20 2011 on XP) QGIS on windows seems not to work as FastCGI, so edit the file


In this section:

  <Directory "C:\OSGeo4W/apps/qgis/bin/">
    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)

3c. 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.


and copy the httpd_qgis.conf file into this directory, then add the following section to the httpd.conf of your apache. Place this at the end of the
config-file and ensure bot to be in any subsection (subsections appear like
this <[sectionsname]> 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 (again, this was not necessary with Apache 2.2.14-4. - October 20 2011 on XP). 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 <layer> in the subtag <name>[YOURLAYERNAME]</name> - please use the <name> not the title!

WARNING: the project file is not reloaded until you restart Apache!!!

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: http://en.wikipedia.org/wiki/Uniform_Naming_Convention#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!

   Report either to the list or to me (adams@terrestris.de)

9. User comments (untested yet)

06. sept. 2011: "thanks for the nice QGIS Server tutorial (http://www.qgis.org/wiki/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."

QGIS Server configuration

QGIS Web Client

QGIS Web Client is generic Web GIS frontend for WMS servers, supporting all additional features of QGIS Server like highlighting and printing.

Source and documentation is available at https://github.com/qgis/qgis-web-client

Extensions to WMS

QGIS supports the WMS 1.3 specification. Additionally, it supports some additional optional parameters and requests:

Map parameter

Similar to UMN mapserver, the map parameter can be used to specify the path to the QGIS projectfile. If not specified, QGIS searches for .qgs files in the directory where the server executable is located.

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?MAP=/home/user/mymap.qgsx%x%...

DPI parameter

The dpi parameter can be used to specify the requested output resolution.

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?....&DPI=300x%x%...

FILTER parameter

Subsets of layers can be selected with the FILTER parameter. Syntax is basically the same as for the QGIS subset string. However, there are some restrictions to avoid SQL injections into databases via QGIS server:

  • Text strings need to be enclosed with quotes (single quotes for strings, double quote for attributes)
  • A space between each word / special character is mandatory
  • Allowed Keywords and special characters are 'AND','OR','IN','=','<','>=','>','>=','!=*,'(',')'
  • Semicolons in string expresions are not allowed

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?REQUEST=GetMap&LAYERS=mylayer1,mylayer2&FILTER=mylayer1:"OBJECTID" = 3;mylayer2:'text' = 'blabla'&....

Note that it is possible to make attribute searches via GetFeatureInfo and leave away the X/Y parameter if a FILTER is there. QGIS server then returns info about the matching features and generates a combined bounding box in the xml output

SELECTION parameter

Vector features can be selected by passing comma separated lists with feature ids in GetMap and GetPrint.

Example: http://myserver.com/cgi/qgis_mapserv.fcgi?REQUESTGetMap&LAYERS=mylayer1,mylayer2&SELECTION=mylayer1:3,6,9;mylayer2:1,5,6x%x%...

GetPrint request

QGIS server has the capability to create print composer output as pdf or pixel format. Print composer windows in the published project are used as templates. In the GetPrint request, the client has the possibilty to specify parameters of the contained composer maps and labels.


The published project has two composer maps. In the GetCapabilities response, they are listed as possible print templates:

<ComposerTemplates xsi:type="wms:_ExtendedCapabilities"><ComposerTemplate width="297" height="210" name="Druckzusammenstellung 1"><ComposerMap width="171" height="133" name="map0"/><ComposerMap width="49" height="46" name="map1"/></ComposerTemplate></ComposerTemplates>

The client has now the information to request a print output:
http://myserver.com/cgi/qgis_mapserv.fcgi?...&REQUEST=GetPrint&TEMPLATE=Druckzusammenstellung 1&map0:EXTENT=xmin,ymin,xmax,ymax&map0:ROTATION=45&FORMAT=pdf&DPI=300

Parameters in the GetPrint request are:
  • <map_id>:EXTENT gives the extent for a composer map as xmin,ymin,xmax,ymax.
  • <map_id>:ROTATION map rotation in degrees
  • <map_id>:GRID_INTERVAL_X, <map_id>:GRID_INTERVAL_Y Grid line density for a composer map in x- and y-direction
  • <map_id>:SCALE Sets a mapscale to a composer map. This is usefull to ensure scale based visibility of layers and labels even if client and server may have different algorithms to calculate the scale denominator
  • <map_id>:LAYERS, <map_id>:STYLES possibility to give layer and styles list for composer map (usefull in case of overview maps which should have only a subset of layers)


Several additional parameters are available to change the size of the legend elements:
  • BOXSPACE space between legend frame and content (mm)
  • LAYERSPACE vertical space between layer title and following items (mm)
  • SYMBOLSPACE vertical space between symbol and following item (mm)
  • ICONLABELSPACE horizontal space between symbol and label text (mm)
  • SYMBOLWIDTH width of the symbol preview (mm)
  • SYMBOLHEIGHT height of the symbol preview (mm)
These parameters change the font properties for layer titles and item labels
  • LAYERFONTFAMILY / ITEMFONTFAMILY font family for layer title / item text
  • LAYERFONTBOLD / ITEMFONTBOLD 'TRUE' to use a bold font
  • LAYERFONTCOLOR / ITEMFONTCOLOR Hex color code (e.g. #FF0000 for red)

External resources

Here are a few links with additional information:






Using OpenLayers with QGIS server:

qgis-web-client.jpeg (159.3 kB) Tim Sutton, 02/01/2012 05:15 am

qgis-web-client.jpeg (46.7 kB) Tim Sutton, 02/01/2012 05:38 am