Publish a Lizmap map from QGIS, step by step

How Lizmap publishing works

A Lizmap map is not a copy of your map: it is your QGIS project itself, read by QGIS Server and displayed in the browser by Lizmap Web Client. Publishing therefore means putting three things in the right place on the server: the QGIS project, its data (except data stored in PostGIS) and a Lizmap configuration file that the plugin creates next to the project.

You need a Lizmap instance online. If you do not have one, the guide Install Lizmap yourself or choose hosting covers both routes. With LizPack Map, LizPack's managed Lizmap hosting, an instance is ready in about four minutes, with QGIS Server and a PostGIS database already connected.

• QGIS Desktop, in a version compatible with the instance's QGIS Server.
• The Lizmap plugin, installed from the QGIS plugin manager.
• A Lizmap instance online and an account allowed to upload projects to it.
• A QGIS project that displays correctly on your computer, with its data kept in its folder or in PostGIS.

Step 1: prepare the QGIS project

Most maps that display badly online have a preparation problem, not a server problem. Before thinking about Lizmap, check your project:

• Relative paths. In the project properties, save paths as relative, and keep the data in the project folder or its subfolders. A path to your C: drive does not exist on the server.
• Coordinate system. Choose the project CRS deliberately; to overlay web basemaps, Web Mercator (EPSG:3857) is the simplest.
• Formats. Prefer GeoPackage to scattered Shapefiles, and PostGIS for edited or large layers.
• Names. Give layers readable names: they are what your visitors will see in the legend.
• QGIS version. Work with a QGIS Desktop version compatible with the instance's QGIS Server, ideally the same one.

Before moving on to the plugin, run a final check: close and reopen the project to make sure no layer is flagged as broken, remove unnecessary working layers, and check that any external basemaps you use are reachable from the internet. A project that opens cleanly on a colleague's computer has every chance of displaying cleanly online, so asking someone else in your team to open it is a quick and effective test.

Step 2: configure the map with the Lizmap plugin

The Lizmap plugin, developed by 3Liz, installs from the QGIS plugin manager (Plugins menu, Manage and Install Plugins, search for Lizmap). It then appears in the Web menu and toolbar. Do not install the plugin named Lizmap server in QGIS Desktop: it is only used on the server. It describes how the map should behave online and saves those settings in a file placed next to the project. In order:

1. Open the Lizmap plugin from the QGIS Web menu and, if the plugin offers it, enter your instance's address so it can check versions.
2. Fill in the map's general information: title, abstract, initial extent and scales.
3. Set up the layers: which are visible at startup, which can be queried, the basemaps and base layers.
4. Enable the tools you need: search, printing from your layouts, measuring, attribute table, editing of PostGIS layers if needed.
5. Save the Lizmap configuration, then save the QGIS project.

The plugin itself reports the problems it detects (layer without a primary key, absolute path, version too recent). Read its warnings before publishing: they prevent most blank maps. The official Lizmap documentation, at docs.lizmap.com, describes each panel of the plugin in detail, from layers and basemaps to the attribute table, editing, filters, charts, atlas and tooltips, if you want to go further than this guide.

Two panels of the plugin deserve particular attention. The base layers panel lets you offer external basemaps, such as OpenStreetMap, without adding them to the project. The tooltip panel controls what visitors see when they click a feature: choose the useful fields and hide the rest. The plugin's official documentation, at docs.lizmap.com, details every panel with examples.

Step 3: publish the Lizmap map with LizPack Publisher

On a standard installation, you copy the project, its configuration and its data into the server's project folder. With LizPack, the free LizPack Publisher plugin does this from QGIS:

1. In QGIS, Plugins menu, search for LizPack and install LizPack Publisher from the official repository. QGIS 3.16 or later is required.
2. Sign in with your LizPack email and password, then choose the instance to work on.
3. With the project open in QGIS, start publishing: it is validated, then sent to the instance with its data.
4. Open your Lizmap portal: the map is there.

LizPack Publisher is also useful day to day: browse the instance's files, open a remote project in QGIS, upload a whole folder while keeping its structure. From the Pro plan, it lets you add tables from the instance's PostGIS database as layers and import a layer into it. Every operation is recorded in a log you can copy for support.

Prefer the browser? The online file manager in the customer area lets you upload, organize and replace projects and data without any plugin.

Publishing PostGIS layers

Files are fine for stable data. As soon as a layer changes often, is shared between several projects or is edited online, PostGIS becomes the right choice: the Lizmap map reads the database directly, without publishing again, and several people can work on it at the same time without overwriting each other's changes.

1. Create a connection in QGIS to your instance's PostGIS database. With LizPack Map, each instance has its own PostgreSQL and PostGIS database; from the Pro plan, you connect to it from QGIS Desktop or pgAdmin over an encrypted connection.
2. Import your layers into the database. From the Pro plan, LizPack Publisher lets you import a layer into the instance's database and run a diagnosis on it, then add tables as project layers.
3. Check that every table has a primary key and a spatial index: without a primary key, identify and editing fail; without an index, the map slows down.
4. Replace the file layers in the project with the PostGIS layers, set the styles, save, then publish again.

Use a connection in the project that also works from the server, not only from your office network or your own computer. A PostGIS layer pointing to a database installed on your own computer will not display online.

Organize the database from the start: one schema per theme or per department, table names in lowercase without spaces, and explicit column names. These conventions avoid many errors between QGIS, Lizmap and the other software that will read the same database, and they make life easier for whoever takes over the project after you. Also keep a record of what each table contains, where its data comes from and when it was last updated.

Allowing online editing

Lizmap lets users enter and change data directly in the browser, without QGIS. That is useful for reporting an issue, a simple field inventory, or updating a status by a department that does not use GIS. You configure it in the editing panel of the Lizmap plugin:

1. Prepare the layer in PostGIS, with a primary key and suitable field types.
2. In QGIS, configure the layer's attribute form: field order, value lists, mandatory fields, default values. Lizmap reuses this form online.
3. In the Lizmap plugin, add the layer to editing and choose the allowed actions: create, modify attributes, modify geometry, delete.
4. Restrict editing to the relevant user groups.
5. Save the configuration, save the project, publish again, then test with an account from the authorized group.

Start with few fields and closed value lists, and test the form with the people who will actually fill it in, on the devices they really use: data entered cleanly from the start is worth more than an exhaustive form nobody fills in. For offline collection on a phone, the QField app is better suited; LizPack Field connects it to the same PostGIS database, so office staff and field teams work on one set of data.

Printing and atlas

Visitors to a Lizmap portal can print the map using the print layouts you created in QGIS. The template, logos, legend, scale bar and texts therefore come from QGIS: what you see in the layout designer is what your users get on paper or in a PDF.

• Provide a few well-named layouts: for example one A4 portrait and one A3 landscape, rather than a dozen variants.
• Use dynamic texts (date, project title) rather than fixed texts that will need correcting.
• Check the resolution: high-resolution printing costs the server computing time.
• Consider the atlas: the Lizmap plugin has a panel dedicated to the atlas, useful for browsing a series of features, for example one sheet per municipality or per parcel.

Step 4: set permissions and share

First decide who should see the map. In the Lizmap administration, you set for each project folder which groups can view it, and you create your users' accounts. A public map needs no sign-in; an internal map is restricted to a group.

To go further, Lizmap modules add features to the portal, such as dashboards built in QGIS. The guide Build a Lizmap dashboard explains how.

1. In the Lizmap administration, create groups matching your audiences: for example one group per department.
2. Create user accounts and attach each one to its group or groups.
3. For each project folder, grant the groups the right to view the projects, and only those groups.
4. Sign in with a test account from each group to check what it actually sees.

Updating a Lizmap map that is already published

A published map evolves: you add a layer, fix a style, change a basemap. The rule is simple: always edit in QGIS, never on the server, then publish again. The project on your computer remains the reference.

1. Open the project in QGIS and make your changes.
2. If you added or renamed layers, reopen the Lizmap plugin to configure them, then save its configuration.
3. Save the QGIS project.
4. Publish again: the project, its configuration and the changed data replace the previous versions on the instance.
5. Reload the map in the browser and check the result, including on a phone if your users open it while out in the field or on the move.

Layers stored in PostGIS are the exception: their data is read directly from the database. A row added or changed in the table shows on the map without publishing the project again. That is one of the best reasons to move your living layers to PostGIS rather than files. Only changes to structure, style or configuration require a new publication.

The most common problems

To track down the cause of a problem, start with the Lizmap plugin's warnings in QGIS, then the LizPack Publisher operations log, which records every upload and can be copied in one click for a support request. Finally, check the map in a private browsing window: you will see exactly what an anonymous visitor who is not signed in sees, which reveals most permission problems at a glance.

Frequently asked questions