QGIS Server on Ubuntu Step-by-step

Update 2016-07-31

For the latest installation instructions, please see the official QGIS Server documentation.

This post summarizes my notes about installing QGIS Server on Ubuntu, adding a QGIS project file to the server and using the WMS in an OpenLayers application.


First, it’s useful to figure out the Ubuntu version:

lsb_release -a

Since my server runs “lucid”, I add the following package sources to /etc/apt/sources.list (as described in the QGIS installation documentation)

deb http://qgis.org/debian lucid main
deb-src http://qgis.org/debian lucid main

Before we can install anything, we need to add the key and update the package list

gpg --keyserver keyserver.ubuntu.com --recv 1F9ADD375CA44993
gpg --export --armor 1F9ADD375CA44993 | sudo apt-key add -
sudo apt-get update

Now we can install QGIS Server and the necessary Apache package

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

It never hurts to restart Apache :)

sudo /etc/init.d/apache2 restart

Let’s test the installation before we proceed. The GetCapabilities request should already work

Adding a QGIS project file

It’s time to add a QGIS project to our server. To do that, we move to the QGIS Server folder

cd /usr/lib/cgi-bin

where you should find qgis_mapserv.fcgi and wms_metadata.xml.
I’ve decided to have one folder for each project file. My first project is “vienna”.

sudo mkdir vienna
cd vienna

qgis_mapserv.fcgi and wms_metadata.xml can now be linked into this new folder

sudo ln -s ../qgis_mapserv.fcgi .
sudo ln -s ../wms_metadata.xml .

The only thing that’s missing anymore is a QGIS project file. It can be copied or linked into the folder. After restarting Apache, we should be good to go.

Let’s test the setup using “Add WMS Layer” in QGIS by adding the service URL such as

and ticking “Ignore GetMap URI …” and “Ignore GetFeature URI …”.

After clicking “Connect”, all layers from the project file we added should get listed and we can select and load them.

QGIS Server can serve as many project files as you want. There are different ways to organize your server but I would simply add a new folder (like the “vienna” folder in this example) and link in the executable and project file.

Using QGIS Server WMS in OpenLayers

Of course QGIS Server doesn’t just talk to QGIS Desktop but to any other WMS client that conforms to the standard. One classic use case is to add the WMS layers to an OpenLayers application. This is rather simple but I’ll add it here for the sake of completeness:

I used to have a Geoserver WMS base layer in my application. The only lines of code that needed to be changed to migrate to QGIS Server were the service URL and the layer names.

wms = new OpenLayers.Layer.WMS(
    'roads', "",
        layers: 'roads',
        format: 'image/png';
        bgcolor: '#fafafa'
        buffer: 1,
        isBaseLayer: true,
        graphicZIndex: 0,

Standardized services are great!

  1. Lenny Sorey said:

    Thank you Anita.

    This is good info.


  2. Ben said:

    I have Ubuntu Precise 12.04. Following similar steps I get Internal Server Error when I try run GetCapabilities request. I know Apache is working as I get the “It Works!” page when I load http://localhost. Any help appreciate. Thanks.

    • Please contact the QGIS developer mailing list. Since Ubuntu 12.04 is brand new, I would not be surprised if there would be some issues. It’s not yet officially supported after all.

    • I haven’t tried Precise yet because I don’t expect things to work from day one. Maybe someone on the mailing list can help.

  3. Stewart King said:

    I have problem with qgis_mapserv.fcgi to read attributes using WMSGetFeatureInfo. For example:-

    new OpenLayers.Control.WMSGetFeatureInfo({
    url: ‘http://localhost/qgis_mapserv.fcgi’ });

    Can show me the proper way to do it using qgis_mapserv.fcgi? Thank you.

    • Sorry, I haven’t looked into that issue before. You might want to have a look at the QGIS Web Client source code.

  4. Hi
    I’ve tried this and QGIS can see the project as WMS, but the only layer it offers is called wfslayer and the “Add layer” button is greyed out. Any ideas?

  5. I had tested it and worked out fine.But when i try to load a wms with OpenStreetMap the wms output doesn’t take its correct position on the map.Could you help me thiw this?Could you explain how to load a wms with OSM?

  6. aborrell said:

    Thank you Anita for (as usual!) valuable info.


  7. Thanks for this great tutorial! Works like a charm for me on Ubuntu Precise!

  8. Juliette Cortes said:

    Dear all,
    I have been trying to write a simple html code to deploy a WMS service. I installed qgis-mapserver in Ubuntu 10.04 followed the instructions above and tested the request with the following url:

    it works ok! Bu when I try to write the code in the html file below, nothing comes out. Could you pls help me to find out a way to publish my simple qgis file

    OpenLayers Example

    var map = new OpenLayers.Map(‘map’);
    var wmslayer = new OpenLayers.Layer.WMS( “QGIS Server Layer”,
    {map:’/usr/lib/cgi-bin/mytrial/trial_roads.qgs’,layers: ‘nyc_roads’, format:’image/png’},
    {singleTile: “true”, ratio:1} );
    map.zoomToExtent(new OpenLayers.Bounds(980618.86082916,207377.49113372,995308.17445088,219926.36191342));

    • Hi Juliette,
      I’m glad that this guide helped you set up QGIS Server. Please use a support site such as http://gis.stackexchange.com for OpenLayers questions. Thank you.

  9. Justin Kueh said:

    Hello Anita

    Thank you for this article — it is very useful. It worked fine until the bit where I copy over my QGIS project. My project has 1 layer. But when I copy it over, and restart apache, and then try to add this project as a WMS layer in QGIS, it can see the project but not the layer in it. I have set paths to absolutely and ticked the 2 “Ignore” buttom options. It simply says that there is “No common CRS for selected layers.” Are you able to help me with this?

    Thank you.

    • Hi Justin,
      Sorry, I haven’t seen this error before. Maybe check the project settings OWS section and the CRS enabled there. For more support, please use the QGIS user mailing list which will bring you into contact with the server developers and many other power users.

%d bloggers like this: