# OpenStreetMap Carto Installation and Customization Guide

> OpenStreetMap Carto is the CartoCSS stylesheet set behind the Standard layer on OpenStreetMap.org. It suits cartographers who can operate PostGIS and Mapnik, but installation requires imported OSM data and auxiliary shapefiles.

**openstreetmap-carto/openstreetmap-carto** — A general-purpose OpenStreetMap mapnik style, in CartoCSS

- Repository: https://github.com/openstreetmap-carto/openstreetmap-carto
- Stars: 1,740 · Forks: 888
- Language: CartoCSS
- License: NOASSERTION
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/openstreetmap-carto-openstreetmap-carto

## Why OpenStreetMap Carto Exists

OpenStreetMap Carto solves a specific cartographic problem: turning OpenStreetMap data stored in PostGIS into a general-purpose Mapnik map style. Its intended users are cartographers and operators who want to render OSM data while retaining control over symbols, colors, feature selection, labels, and zoom-dependent presentation. The project is not merely a sample application. According to the README, these CartoCSS stylesheets have been used for the Standard map layer on OpenStreetMap.org since August 2013, and they are updated from each point release.

That production history makes the project different from a small rendering demonstration. It also raises the adoption bar. The repository describes the style as easily customized, but customization happens within a large cartographic system containing Mapnik, CartoCSS, PostGIS, imported OSM data, SQL functions, indexes, Lua transforms, fonts, symbols, patterns, and external shapefiles. A team that only needs a web map embedded in an application should not begin by deploying this repository without checking whether a hosted map or a simpler renderer meets the requirement.

The repository also distinguishes itself from the former XML-based OpenStreetMap stylesheets. The Carto project supersedes those stylesheets and provides the current design in CartoCSS. This is useful for operators already familiar with the former Mapnik XML design, but it does not remove the need to understand Mapnik rendering or the database schema expected by the style.

## CartoCSS, Mapnik, and the PostGIS Rendering Path

The repository layout shows the main parts of the rendering system. `project.mml` is the Mapnik project entry point, while `style/` contains the stylesheets. Supporting directories and files include `symbols/`, `patterns/`, `road-colors.yaml`, and `external-data.yml`. SQL resources such as `functions.sql`, `indexes.sql`, `common-values.sql`, and `indexes.yml` support the PostGIS side, while `openstreetmap-carto-flex.lua` handles the import-oriented flex configuration.

The broad data flow is database to Mapnik rendering, with CartoCSS providing the cartographic rules. OSM data must first be loaded into PostGIS using the schema expected by the selected release. Auxiliary shapefiles are also required, as stated in the README installation section. The Mapnik project then consumes that prepared data, and the CartoCSS processor or Kosmtik converts the style into something Mapnik can render. The README identifies both Kosmtik and the command-line CartoCSS processor as compatible processors.

This architecture makes feature decisions more than cosmetic choices. A request to show another OSM tag can require changes to the Lua import transform, the database schema, and the CartoCSS rules. Version 4 added osm2pgsql Lua transforms and an hstore column containing other tags. Version 5 updated Lua transforms and changed line and polygon decisions. Version 6 moved to the osm2pgsql flex backend. Such changes affect how data reaches the renderer, not just how lines or polygons are colored.

## Installing OpenStreetMap Carto for a First Render

The README does not provide a standalone quick-start command. It directs users to `INSTALL.md` and states that installation requires a PostGIS database populated with OpenStreetMap data, plus auxiliary shapefiles. A checkout alone therefore cannot produce a map. The repository includes Docker assets, but the README does not document a complete first-run command.

For a Kosmtik installation, `Dockerfile` documents the underlying tool setup. It installs Kosmtik from a pinned Git commit rather than the package release channel. This is the installation command recorded in `Dockerfile`:

```bash
npm set prefix /usr && npm install -g --unsafe-perm "git+https://git@github.com/kosmtik/kosmtik.git#5dbde8db6b5e22073951066b0646a91c10bb81a5"
```

After that installation, the same file installs a defined set of Kosmtik plugins:

```bash
kosmtik plugins --install kosmtik-overpass-layer \
                    --install kosmtik-fetch-remote \
                    --install kosmtik-overlay \
                    --install kosmtik-open-in-josm \
                    --install kosmtik-map-compare \
                    --install kosmtik-osm-data-overlay \
                    --install kosmtik-mapnik-reference \
                    --install kosmtik-geojson-overlay
```

These commands prepare the rendering tool, but they do not populate PostGIS or fetch the auxiliary shapefiles. Follow `INSTALL.md` for the data preparation and renderer startup sequence associated with the release being used. A successful first render should compile `project.mml` against a populated PostGIS database and produce the OpenStreetMap Carto design rather than an empty map or a database connection error.

The repository's `docker-compose.yml` separates `kosmtik`, `db`, and `import` services. This structure confirms that rendering, database storage, and OSM import are distinct concerns. It is not a turnkey single-process development environment.

## Docker Compose Services for Local Cartographic Work

The Docker configuration offers a concrete composition of the required infrastructure. The `kosmtik` service builds from `Dockerfile`, mounts the repository at `/openstreetmap-carto`, depends on `db`, connects through `PGHOST=db` and `PGUSER=postgres`, and exposes port `6789` only on the host's loopback address.

The database service builds from `Dockerfile.db` and configures PostgreSQL with `POSTGRES_HOST_AUTH_METHOD=trust`. That setting belongs to the repository's local container composition and should not be treated as a production authentication design. The import service builds from `Dockerfile.import`, shares the database dependency, mounts the same repository path, and exposes database and import-related variables to the container.

The relevant host binding is fixed in `docker-compose.yml`:

```yaml
ports:
  - "127.0.0.1:6789:6789"
```

Binding it to `127.0.0.1` avoids direct network exposure through that mapping. The import service also accepts `OSM2PGSQL_CACHE`, `OSM2PGSQL_NUMPROC`, `OSM2PGSQL_DATAFILE`, and `EXTERNAL_DATA_SCRIPT_FLAGS`, while PostgreSQL memory variables are passed to the database and import services. These controls matter for large imports, but the README does not prescribe values. Operators should follow `INSTALL.md` and `DOCKER.md` for compatible inputs rather than copying arbitrary tuning settings.

## Version Boundaries That Affect Tile Operations

OpenStreetMap Carto uses `MAJOR.MINOR.PATCH` versioning, and the version number communicates more than API compatibility. According to the README, PATCH releases contain bug fixes and should have no reason not to upgrade. MINOR releases occur every two to five weeks and may alter what appears, how it appears, which features exist, or the associated assets. Such visual changes can require rendering checks even when no database reload is needed.

MAJOR releases define larger operational boundaries. The documented history says a database reload or dependency upgrade triggers a major version change. Version 4 required a database reload and did not retain compatibility with version 3. Version 5 changed Lua transforms and decisions about line strings and polygons. Version 6 adopts the flex backend. A renderer operator therefore cannot evaluate an upgrade only by checking whether CartoCSS syntax changed.

Maintenance status needs a narrow description. The repository is not archived, and its last push was on 2026-09-20. That is a recent repository change, but it does not establish that every rendering toolchain is compatible with the current branch or that public issues have scheduled delivery. There are no GitHub releases listed, so operators should not assume a package-style release entry exists in that location. The README's versioning policy and the repository's `RELEASES.md` file are more relevant sources for release selection.

For a public tile service, MINOR changes can alter the map's appearance. For a private deployment, they can still trigger asset, cache, and regression review. The README states that further technical and design work depends on available community effort, so issue resolution and ongoing changes should not be represented as guaranteed service levels.

## Customization Boundaries and Cartographic Constraints

The README presents the stylesheets as suitable for custom cartography, and `CARTOGRAPHY.md` records the project's design goals and guidelines. That is valuable when a team needs to depart from the standard appearance while retaining a coherent rendering approach. Colors, line widths, labels, symbols, and zoom rules can be changed, but each visual request should be checked against the underlying feature availability in PostGIS.

The project's version history shows why CSS-like customization is not the whole story. Older tagging approaches were removed because they were rarely used. Newer releases changed schema and import decisions to expose more data and support different rendering needs. A style rule cannot compensate for a field that the import process does not populate. Database and import work may precede the visual change.

The README also says the project avoided excessive variables and expressions because advanced constructs can make contributions harder. That is an intentional maintainability trade-off. Convenient abstractions may reduce repeated configuration, but they also raise the effort required for another contributor to understand and modify the style. For a large public style, readable and reviewable changes may be worth more than compact configuration.

Custom deployments must also account for fonts, symbols, patterns, shapefiles, SQL functions, and the selected Mapnik and CartoCSS versions. The README says MINOR releases rarely change assets and normally do not require software or database upgrades. MAJOR releases explicitly may require both. Treat a major-version change as a coordinated rendering-stack change rather than a stylesheet file swap.

## Alternatives to the CartoCSS Rendering Path

The clearest documented alternative is the former XML-based stylesheet repository. Both approaches target Mapnik rendering of OpenStreetMap data, but they express the map design differently: OpenStreetMap Carto uses CartoCSS, while the older project uses Mapnik XML. OpenStreetMap Carto also includes Lua and database changes for modern OSM data handling, but the documentation does not establish that the XML project supports the same schema or import contract. The README states that the Carto stylesheets supersede the XML-based stylesheets.

The README also lists OSM Bright, OpenStreetMap "FR" Carto, and OpenStreetMap Carto German as open-source alternatives. These projects are relevant to organizations comparing presentation or community-specific design, but their repositories are not documented in this project. A technical comparison would require their installation requirements, supported schemas, renderer versions, and customization mechanisms.

For a team without a Mapnik and PostGIS rendering operation, a hosted or client-side map service may be a more practical alternative than another local stylesheet. OpenStreetMap Carto assumes that its users can prepare a populated database, obtain auxiliary data, compile the style, and manage upgrades. Switching to another CartoCSS project does not remove that infrastructure requirement unless its documentation describes a simpler deployment path.

## Licence Review for Redistributed and Modified Styles

GitHub classifies the repository licence as `Other`, and the README points readers to the licence documentation. The repository contains `LICENSE.txt`. Reviewing that file is necessary before copying styles, symbols, fonts, configuration, or modified versions into a commercial or public rendering service.

The README does not reproduce the licence terms, so this article cannot state whether redistribution, attribution, warranty disclaimers, or compatibility with a particular organizational policy are required. The licence is described as custom and not classifiable by GitHub's standard category. That distinction makes replacement of the project name in a conventional MIT, BSD, or Apache-style template unsafe.

The use of `fonts-unifont` in `Dockerfile` also makes it important to distinguish repository licensing from dependency and packaged-asset licensing. A font package appearing in the container does not by itself document that package's obligations. Operators should inspect `LICENSE.txt` and the licence information for every redistributed asset before publication. This is a compliance review, not a conclusion that any particular use is permitted or prohibited.

## Conclusion

OpenStreetMap Carto is appropriate for organizations that already operate a PostGIS and Mapnik rendering stack and want to adapt a style with an established history on OpenStreetMap.org. It is a poor choice for a lightweight preview, a turnkey tile server, or an application that cannot absorb schema and dependency changes. Before adoption, verify the current INSTALL.md requirements, inspect the custom LICENSE.txt, and confirm that your rendering software supports the flex backend and Lua transforms required by the current major version.

## FAQ

### What does OpenStreetMap Carto need before it can render a map?

It needs a PostGIS database populated with OpenStreetMap data and auxiliary shapefiles. The README directs users to `INSTALL.md` for the full installation procedure.

### Which rendering tools can process OpenStreetMap Carto?

The README states that the stylesheets work with Kosmtik and the command-line CartoCSS processor. The project also uses Mapnik for rendering.

### When does upgrading OpenStreetMap Carto require a database reload?

The README's versioning policy says a database reload or dependency upgrade triggers a MAJOR version change. For example, version 4 required reloading the database and did not retain version 3 compatibility.

## Sources

- [Issues](https://github.com/openstreetmap-carto/openstreetmap-carto/issues)
- [openstreetmap-carto/openstreetmap-carto on GitHub](https://github.com/openstreetmap-carto/openstreetmap-carto)
- [README](https://github.com/openstreetmap-carto/openstreetmap-carto/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/openstreetmap-carto-openstreetmap-carto