Home / GIS and Open Map Data for Beginners

QGIS Web Map: Export Your Project to a Self-Contained Web Map with qgis2web

HTML and CSS code on a monitor, the building blocks of a web page

Photo: Bibek ghosh / Pexels

Ask ten QGIS users what a QGIS web map is and you will collect three different technologies: a hosted publication, a live server, and an exported folder of files. This guide owns the third, because it is the one most people reaching for the phrase actually need. The qgis2web plugin exports your QGIS project to a self-contained web map: static HTML, JavaScript, and CSS files that any web host, from a university server to a free static hosting account, can serve, and that any browser can open, even from a local folder. Your layers, your styling, your popups and labels are translated into one of the web's mapping libraries and shipped as a folder. There is no database, no FastCGI, no account, and nothing to patch. The neighboring routes are real and are handed off honestly below: QGIS Server and QGIS Cloud serve the project live, and embedding OpenStreetMap itself is a different job owned by other guides. Here, the subject is the export: what qgis2web builds, how its choices work, and how to produce an export that does your project justice.

Interactive tool

Ship the Folder: The Web Map Export Checklist

Check off each step as you finish it. Your progress stays on this page.

0 of 7 complete

0% done

What the Export Actually Is

Run qgis2web and it writes a folder: an index.html, the JavaScript libraries, your data converted to web-friendly formats, and the style definitions translated from your QGIS project. Open the index file in a browser and the map appears, styled as you styled it, with a layer control, popups on click, and the extent you set. Host the folder anywhere static files live and the same map appears at a URL. Three properties define the species. It is a snapshot: the export freezes the data as it was at export time, and updating the map means exporting again. It is self-contained: the folder carries its dependencies with it, which is why it works from a USB stick and survives its host being a plain file server. It is a translation, not the original: QGIS's renderer is not in the folder; the plugin re-expresses your symbology in the web library's language, and most of a normal project's styling survives the translation while exotic effects may simplify. Hold those three properties in mind and every setting below makes sense: you are publishing a translated snapshot, and the craft is in choosing what the snapshot contains.

Choosing the Library: Leaflet or OpenLayers

The plugin's first choice is the target library, and it is a real fork. Leaflet is the lightweight, widely known web mapping library: the export is compact, the behavior familiar to anyone who has used a web map, and the plugin's Leaflet output is its most travelled path. OpenLayers is the heavier, more capable library, with strengths in projections and complex layer handling that matter when your project leans on them. A third renderer, Mapbox GL JS, is also documented in the plugin's ecosystem for vector-tile-oriented output. The working guidance: choose Leaflet unless you have a reason; its exports are the smallest and its popups and controls the most predictable translation of a desktop project. Choose OpenLayers when the project needs what Leaflet's model handles awkwardly, such as demanding projection work. Either way, the choice is per export, not per project, so an experiment costs one re-export: produce both, open both, and let the project's own behavior arbitrate. What you should not do is choose by fashion; the libraries are delivery vehicles, and the cargo is your map.

A close-up of multicolored programming code on a computer screen
A close-up of multicolored programming code on a computer screen

The Settings That Decide Quality

The export dialog's options cluster into four decisions. Extent: export the full project extent or the current canvas view; a web map framed on the data, rather than on a desktop session's wandering viewport, is the difference between a publication and a screenshot's cousin. Basemap: add a tile basemap beneath your layers or ship your data alone; a basemap gives readers their bearings and costs the map its offline purity, since tiles stream from their provider. Popups: the plugin builds popups from your layers' attributes, and the craft is in curation: a popup showing every field in a forty-column table is a data dump wearing a map's clothes, so choose the fields a reader actually wants, in the order they want them, using the layer's display settings as your guide. Labels: labels can be exported, and they reward restraint, since web label placement lacks the desktop engine's finesse. Behind all four sits the Update Preview loop, the plugin's built-in preview of the export as you adjust it: use it as the workflow, not as a final check, changing one decision at a time and watching the map respond, because the preview is the only place the translation's losses are visible before your audience finds them.

Data Weight: The Snapshot's Physics

A static export carries its data with it, and data has weight. Vector layers are converted and shipped as files the browser must download and draw, so a layer that feels light on the desktop, a national road network, a million building footprints, can make a web map that loads like a truck. The disciplines are unglamorous and decisive. Clip to the story: export the study area, not the continent the study area came from. Simplify for scale: geometry drawn for a screen at city zoom does not need survey-grade vertex density, and the export settings and a preprocessing pass can shed vertices the reader will never see. Mind the attribute table: every field you ship is downloaded by every visitor, so drop the working columns and keep the popup's cast. Test on a slow connection and a phone, because your audience includes both, and the desktop's gigabit and GPU are not evidence. A qgis2web export is a publication with a file size, and respecting the reader's bandwidth is part of the cartography.

Hosting the Folder

Because the export is static, hosting is the simplest step and the one newcomers overthink. Any static web host serves the folder as-is: a directory on an existing web server, a static hosting service, a GitHub Pages site, an intranet share exposed over HTTP. Upload the whole folder with its structure intact, and the map's address is the folder's address. Two cautions travel with the simplicity. Keep the folder together: the index file references its scripts, styles, and data by relative path, so cherry-picking files out of the export breaks it in ways that look like the map's fault. Mind the basemap's terms: if your export leans on a tile basemap, the tile provider's usage policy governs your popular map, and a map expecting real traffic should sit on tiles it has the right to use at that volume. Beyond those, the operational story is the static web's story: nothing to patch, nothing to restart, and a map that will still load in ten years if the folder survives, which is more than most live services promise.

The Honest Boundary: Where Exports Stop

The OSGeo project page for this ecosystem draws the line plainly, and this guide repeats it because it saves real projects: a static export is not the route for authenticated or server-side applications. If the map must know who is asking, must answer with data too large to ship, must reflect a database that changes hourly, or must accept edits from its audience, the job belongs to a server: QGIS Server for your own infrastructure, QGIS Cloud for the hosted route, both linked below. The export's side of the line is wide and honorable: publications, reports with maps that outlive the meeting, project deliverables, teaching materials, offline field references, and the ninety percent of web maps that are, in truth, finished maps being shown to people. Choosing the export when the job is on its side of the line is not settling; it is matching the tool to the physics. Choosing it across the line is how projects end up re-built in month three, and the re-build, not the export, is the expensive part.

Translation Losses, and How to Catch Them

Because the export is a translation, some of the desktop's language has no exact web equivalent, and the professional skill is knowing where the accent slips. Blend modes between layers, the multiply and overlay tricks of desktop cartography, generally do not survive: the web libraries stack layers by opacity, so a project whose meaning depends on blending needs its key effects baked in beforehand or redesigned. Elaborate symbology simplifies: complex marker constructions, geometry generators, and data-defined overrides may render approximately or not at all, while the bread-and-butter styles, categorized and graduated fills, rule-based basics, standard labels, translate faithfully. Label placement loses the desktop engine's collision intelligence, so dense label fields that the desktop resolves elegantly can overlap on the web. The catching discipline is the preview loop used as an audit: export, then walk the map feature class by feature class against the desktop canvas, checking each layer's appearance, popups, and labels at the zooms readers will use, and keep a short list of the project's known simplifications so a redesign fixes causes rather than symptoms. Most projects pass the audit with a handful of adjustments; the ones that fail instructively are those whose authors never looked. A translation read carefully is a publication; a translation shipped unread is a rumor about your map.

Keeping the Export Evergreen

A static map ages in two ways, and both have cheap remedies. Its data ages, answered by a re-export on whatever rhythm the subject moves at, with the export settings saved in your project notes so the new snapshot matches the old one's framing, extent, and field choices exactly. Its context ages more quietly: the basemap tiles it leans on are live, the links around it move, the organization renames itself. A yearly open of your own published map, clicked through like a stranger, catches both kinds of aging while they are still embarrassments rather than evidence. The export's permanence is its virtue; a small maintenance habit is the rent that virtue charges.

Related Guides

If this page answered part of the question, these GIS guides cover the rest of the same ground:

Frequently Asked Questions

What does qgis2web produce?

A self-contained folder: an index.html plus JavaScript, CSS, your data converted to web formats, and your styling translated into the chosen library. Any static host can serve it, and it opens from a local folder in a browser.

Should I export to Leaflet or OpenLayers?

Leaflet by default: compact exports and the most predictable translation of a desktop project. OpenLayers when the project needs its strengths, such as demanding projection handling. The choice is per export, so you can produce both and compare.

Does a qgis2web map update when my data changes?

No. The export is a snapshot of the data at export time. Updating the map means exporting again, which is quick, but automatic freshness belongs to the server routes.

Can a qgis2web map work offline?

The map and its shipped data can, if you open the folder locally or host it on a local network. A tile basemap breaks offline use, because tiles stream from their provider; ship your own data alone for a fully self-contained map.

When should I use QGIS Server instead of an export?

When the map needs authentication, server-side data too large to ship, hourly freshness from a live database, or input from its audience. The export owns finished maps being shown; the server owns applications.

Photo credits: Bibek ghosh (Pexels); Myburgh Roux (Pexels). Photos are served from this site; follow the credit to the library page for the original.