Nextcloud Maps: your location history inside your own cloud

What the app actually shows

Nextcloud Maps presents itself as the whole world fitting inside your cloud, and the feature list is the best description of it. The map itself uses OpenStreetMap and Leaflet, and you can choose between a standard map, satellite, topographical, dark mode or even a watercolor style. Favorites let you save places privately, with syncing to GNOME Maps and mobile apps planned. Routing is possible using either OSRM or Mapbox. Photos appear on the map directly rather than as a separate slideshow, so you can see where you were. Contacts are shown on the map so you can see where your friends live and plan a visit. Devices appear too, which the README frames as the answer to a lost phone. And tracks let you load GPS tracks or past trips, with recording via PhoneTrack or OwnTracks planned. The theme is consistent across all of these: the location data lives in the cloud you already control rather than in a separate commercial service.

A map is a folder, not an object

The design decision that makes this app fit into Nextcloud rather than sit beside it is that a custom map is a folder in the files app. Custom maps are stored by default in a `/Maps` folder, which you can find in the files app, and any other folder becomes a map by placing a `.index.maps` file into it. Because it is all folders, content can be added through WebDAV from desktop and mobile clients, through the files app, or through the Maps app itself, and a custom map can then be shared from the maps app or from any other app using the standard Nextcloud sharing system. That is a real architectural choice rather than a convenience. The app can then layer its own formats onto that base. Favorites on a custom map live in a `.favorites.json` file, and linked favorite categories from other people are read-only, editable only on the owner's default map, with the links stored in a `.favorite_shares.json` file. Contacts on a custom map are vCards, `*.vfc` files. Tracks are `*.gpx` files. Photos are simply the photos in the corresponding folder, added from files or from maps, and existing photo albums show up on the map by way of the same `.index.maps` marker.

The front end is Vue on MapLibre

The repository is a JavaScript project with a PHP back end, and the package.json shows the shape of the front end. The main entry is `main.js` and the module type is ESM, with a Vite build in development, watch and production modes, and separate lint and stylelint scripts that cover `src`. The mapping stack is MapLibre GL, with `maplibre-gl` at version 5, `vue-maplibre-gl` for the Vue binding and `@maplibre/maplibre-gl-directions` for routing, and the README notes MapLibre-GL support explicitly. The UI framework is Vue 3, and around it sit a set of first party Nextcloud packages for auth, axios, dialogs, the event bus, files, initial state, l10n, moment, paths, router, sharing, upload and the component library `@nextcloud/vue`. Other dependencies give a sense of what the app does: `chart.js` for charts, `geojson` for the data format, `nouislider` for range controls, `ua-parser-js` for user agent parsing, and Font Awesome and Material Design icons.

Building it from source

The development setup requires node and npm, and the README gives four steps. You clone the app into the `apps` folder of your Nextcloud with `git clone https://github.com/nextcloud/maps.git`. In the folder of the app you run the command `make` to install dependencies and build the JavaScript. Then you enable the app through the app management of your Nextcloud, and from there the README invites you to help fix issues and review pull requests. The node requirement is specific, with the engines field asking for node 22 or newer and npm 10.5 or newer. The repository is set up for a fairly wide toolchain, with a `composer.json` and lock file for the PHP side, an `openapi.yml` for the API, a `psalm.xml` for static analysis, `rector.php` for automated refactoring, a `krankerl.toml` for packaging, a `stylelint.config.cjs` for the styles, a `vite.config.ts` for the build, a `.tx/` directory for translations, and separate `l10n/` and `src/` trees for the PHP and JavaScript halves.

Photo scanning is a background job, and that has consequences

The admin documentation covers the one operation that will otherwise look like a bug. Media scans are performed with the regular system background job, and they can also be triggered manually through occ commands, with `./occ maps:scan-photos` to rescan photos' GPS exif data and `./occ maps:scan-tracks` to rescan track files. The reason this matters is stated in the user documentation: scanning photos takes time, so photos are scanned in the background, and after adding photos it might take a while until the scan is done and the photos are shown on the map. So on a large photo library, adding a folder to a map does not produce pins immediately, and an administrator who has just moved a few thousand photos will see an empty map for a while. The occ commands are the way to force it, and they are the way to recover after replacing a photo library. The readme's own phrasing about tracks, that recording with PhoneTrack or OwnTracks is planned, marks the boundary of what exists today for live location capture.

What is finished and what is on the list

The README separates current features from future plans, and the plans section is worth reading because it shows where the design is heading. Events on the map, so you know where you need to go next, is the first item. The second is different projections, and the argument for it is a specific one: the Mercator projection is very biased, as you can see from a linked demonstration, and another view like the Gall-Peters projection would be a possibility. That is a well made point about a well known problem, and the fact that it is listed as a plan rather than a toggle tells you the map rendering is currently Mercator. Elsewhere in the same list, favorites syncing to GNOME Maps and mobile apps is planned, as is track recording with PhoneTrack or OwnTracks. The current release line is v1.8.0, published on 2026-08-21, with v1.7.1 and v1.7.0 both from 2026-06-10, and the last push was on 2026-10-20, so the app is being worked on even though the tags move in a slower rhythm.

Where this is the wrong choice

The limits are mostly about the scope of the map and about who provides the tiles. First, the map data is not yours in the way the location data is. The tiles come from OpenStreetMap and the styles are external, so a self hosted Nextcloud still depends on a third party for the basemap, and there is no offline tile caching described in the documentation. The privacy story is about your tracks, photos and contacts, not about the tile requests. Second, routing is delegated. OSRM and Mapbox are both external to the app, and Mapbox in particular is a commercial service, so a route computed in a self hosted instance may leave it. Third, the feature set is a viewer and a planner, not a navigator, and there is no turn by turn guidance. Fourth, the format conventions are clever but they are conventions, and a folder becomes a map because of a dot file, which means a user who renames or reorganises folders can break a share or lose the association. Fifth, the app is JavaScript heavy, with Vue, MapLibre, Chart.js and a range slider all loaded in the browser, so on a low powered client the map view is the heaviest part of a Nextcloud install. And sixth, the contacts and device features raise the question of who can see them, which is a Nextcloud sharing question as much as a maps question, and one the app's own documentation does not try to answer.

Editorial conclusion

Nextcloud Maps fits a Nextcloud administrator who wants location data in the same place as the files and photos it describes, since the app is a view over ordinary folders and a background job rather than a separate service with its own storage. It is the wrong choice if you need turn by turn navigation, since routing is delegated to OSRM or Mapbox and the app is a planner rather than a navigator, and the wrong choice if you need offline tiles, since the map data is fetched from OpenStreetMap and the tile styles. Before you deploy, plan the photo scan, because scanning is a background job and the README warns it takes time, and read the custom map conventions, since a map is a folder with a marker file rather than a separate object. The last push was on 2026-10-20, the newest release is v1.8.0 from 2026-08-21, and the licence is AGPL-3.0.

Frequently asked questions

Official sources

1. License: AGPL-3.0
2. nextcloud/maps on GitHub
3. Project website
4. README
5. Releases