Every map style is an argument about what matters, and the standard OpenStreetMap style makes its argument in public, in code anyone can read and change. That code is openstreetmap-carto, and its language is CartoCSS: stylesheets that say, in so many rules, that motorways burn orange-red, that footpaths whisper in dashes, that a hospital earns its icon at this zoom and not before. To write a custom style in this ecosystem is to edit that argument: recolor the roads for a cycling audience, quiet the landuse for a data-quality map, or fork the whole stylesheet into a cartography of your own, as real projects have done. This guide teaches the authoring system itself: the project's structure, the compiler that turns stylesheets into renderer instructions, and the CartoCSS mechanisms, variables, layer blocks, filters, and attachments, that every change from a single color to a full fork is built from. The vector-tile style document, the other great way to restyle OpenStreetMap, is a different artifact owned by the vector tiles guide linked below; this guide owns the raster tradition, the standard style's own lineage.
Home / GIS and Open Map Data for Beginners
OpenStreetMap Custom Style: Writing Your Own osm-carto Style in CartoCSS

Photo: Pavel Danilyuk / Pexels
Argue in CartoCSS: The Custom Style Checklist
Check off each step as you finish it. Your progress stays on this page.
0 of 7 complete
0% done
The Project: project.mml and the MSS Files
An osm-carto checkout is organized as a small publishing system. At its center sits project.mml, the project file, written in a YAML-like structure, which declares the stylesheet's layers: each entry names a layer, points at the data source it draws from (the familiar osm2pgsql-loaded database tables), and attaches the style files that govern it. Around it live the MSS files, the actual CartoCSS stylesheets, organized by subject: roads in one, water in another, boundaries, buildings, landuse, and the rest, so a cartographer editing road casings opens the roads file and finds the whole argument about roads in one place. Symbols, icons, and patterns live alongside as assets the stylesheets reference. The structure teaches the first lesson of the system: data and decoration are separate files. The mml says what exists and where it comes from; the mss says how it looks; and a custom style, at minimum, is an edit to the second that leaves the first almost alone.
The Compiler: From CartoCSS to mapnik.xml
CartoCSS is not consumed by the renderer directly. The carto command compiles the project, mml plus mss, into a single mapnik.xml, the configuration the Mapnik rendering engine actually reads. This indirection is the system's ergonomics: CartoCSS offers variables, nesting, and arithmetic that raw Mapnik XML would make unbearable, and the compiler flattens them into the verbose XML the engine wants. The working loop of every style author follows from it: edit an MSS file, recompile, render a test image, look, repeat. Two consequences deserve emphasis. First, the compiled file is a build artifact: you version and share the CartoCSS sources, and treat mapnik.xml as output, regenerated on demand. Second, errors live at two levels: a CartoCSS syntax mistake stops the compiler, while a rule that compiles can still be cartographically wrong, visible only in the render, which is why the render step is not optional in the loop. Style authoring is programming with a visual test suite, and the test is a map.

The Language: Variables, Blocks, Filters, Attachments
CartoCSS reads like CSS that grew up in a map room, and four mechanisms carry nearly all of it. Variables name the palette: a color defined once as a variable and referenced across files, so the one-color change that beginners dream of, make the motorways blue, is literally a one-line edit when the original authors were disciplined, and a treasure hunt when they were not. Layer blocks scope rules to a layer from the project file, and within them, zoom conditions gate rules by scale, the mechanism behind every feature that appears at zoom 14 and not 13: the style is a function of zoom as much as of geography. Filters select by the data's own attributes, the bracketed conditions that match tag values, way_pixels thresholds, and feature classes, so a rule can speak to motorways and not to the paths that share their layer. Attachments solve the casing problem and its kin: a single road needs several passes, a wide dark casing beneath a narrower bright fill beneath a centerline dash, and attachments let one feature be drawn in stacked instances, the ::casing beneath the body, each with its own rules. Master those four, variables, blocks with zoom gates, filters, attachments, and the standard style stops being a monument and becomes a text you can argue with.
The Ladder of Changes
Custom styles are best learned as a ladder, each rung a complete and useful act. Rung one: retune the palette. Change variables, recompile, render: the standard map in your organization's colors, or with a landuse scheme quiet enough for data to sit on top. Rung two: retune emphasis. Adjust widths, zoom gates, and label rules so the features your audience cares about arrive earlier and speak louder; a hiking style that promotes paths and demotes motorways is mostly this rung. Rung three: add and remove features. Write new filter blocks for data the standard style ignores, and silence layers it draws that your map does not need; here the mml's layer list and the database's contents become your concern, not just the palette. Rung four: fork. Take the whole project as the foundation of an independent cartography with its own name, governance, and release rhythm. Each rung is respectable; most real needs live on rungs one and two, and the ladder's lesson is that a fork is a commitment, not a starting point.
CyclOSM: The Fork That Proves the Ladder
The proof that rung four can reach the world is CyclOSM: a cycling-focused cartography built as a fork of openstreetmap-carto, which promotes cycleways, bicycle infrastructure, and the features riders navigate by, and which earned a place among the featured layers on openstreetmap.org itself, offered to every visitor as one of the map's official faces. CyclOSM matters to this guide for two reasons. It demonstrates that the standard style is a platform, not a ceiling: the same database, argued differently, serves a different public without new data. And it demonstrates the fork's true costs and rewards: an independent project must track the upstream style's evolution, maintain its own rendering, and govern its own cartographic arguments, in exchange for which it can become, as CyclOSM did, a layer the whole project stands behind. Our basemaps guide tours CyclOSM as a finished face; here it stands as the worked example of the authoring road's far end.
Rendering Your Style, and the Honest Limits
A compiled style needs a renderer and data to draw: the standard stack pairs Mapnik with an osm2pgsql-loaded database, the same pipeline the tile server guide describes, and most authors develop against a small extract, a city or a region, where renders are fast and mistakes are cheap. Scale the extract only when the style survives the city. The honest limits close the guide. CartoCSS governs the raster tradition: if your destination is a vector tile service with client-side styling, the style document there is a different artifact in a different language, owned by the vector tiles guide. And a custom style inherits the database's truth: no stylesheet can draw what the data does not contain, so half of advanced style work is discovering which tags and geometries your extract actually holds. Within those limits, the system is complete and open: the standard map's own source, a compiler, and your argument about what matters. That is an invitation few cartographic traditions have ever extended, and it is sitting in a repository waiting to be cloned.
The Data Beneath the Style: osm2pgsql and the Tables
A style can only draw what its database holds, and osm-carto's database has a shape every serious author learns. The data arrives through osm2pgsql, which loads OpenStreetMap extracts into PostgreSQL tables organized for rendering: the point, line, polygon, and roads tables whose columns the project file's layers query. Modern osm-carto leans on osm2pgsql's flex output and Lua tag processing, which decide at import time which tags become columns and which computed fields, a road's class rollup, a name's language variants, the style will have to reason with. The consequence for authors is that style work and data work interlock: a filter in an MSS file can only match a column the import created, so adding a feature to the map can mean changing the Lua processing, reimporting the extract, and only then writing the rule, a pipeline our tile server guide describes from the operations side. It also explains the standard style's conservatism: every new drawn feature is a negotiation among the tag's prevalence in the data, the column's cost at import, and the rule's clarity at render. Authors who grasp the pipeline stop asking why the style ignores a tag they love and start reading the import configuration, which is where the answer lives.
Labels: Where Styles Are Won and Lost
Roads get the glory, but labels decide whether a custom style feels professional, and osm-carto's labeling system is its own discipline inside the MSS files. Road names follow their lines with shields on the classified network, place names are ranked by the settlement hierarchy so a zoom level shows the places that matter at that scale, and water, peaks, and neighborhoods each have their placement logic, all gated by zoom and filtered by the data's own importance signals. The custom author's label work is mostly judgment about priority and air: which names appear first as you zoom in, which are allowed to collide and vanish, how much of the map's surface text may claim before the geography drowns. Change a palette and the map looks different; change the label hierarchy and the map reads different, which is the deeper intervention. Test label work at the awkward middle zooms, where density peaks, and read the render as a stranger would, because a style's labels are its voice, and voices are judged in sentences, not in word lists.
Related Guides
If this page answered part of the question, these GIS guides cover the rest of the same ground:
- OpenStreetMap Vector Tiles: Data Plus Style, Separated: The other styling tradition: the vector style document, handed off there.
- OpenStreetMap Basemaps: The Featured Layers Toured: The finished faces, including CyclOSM, that authoring produces.
- OpenStreetMap Tile Server: The z/x/y Raster Stack: The rendering pipeline a compiled style feeds.
- OpenStreetMap Tags: The Grammar of the Database: The attributes every filter in your stylesheet will match against.
Frequently Asked Questions
What is CartoCSS?
The stylesheet language of openstreetmap-carto, the standard OpenStreetMap style. CartoCSS files (MSS) plus a project file (project.mml) are compiled by the carto command into the mapnik.xml that the Mapnik renderer consumes.
What is the difference between project.mml and the MSS files?
The project file declares the layers and their data sources; the MSS files hold the styling rules for those layers, organized by subject such as roads and water. Data and decoration live in separate files, and most custom work edits the MSS side.
How do I change one color in the standard style?
Find the variable that defines it, since osm-carto names its palette as variables referenced across the stylesheets, change it, recompile with carto, and render a test image. The edit is one line when the variable discipline holds.
What is a style fork, and should I make one?
A fork is an independent cartography built on the whole osm-carto project, like CyclOSM, the cycling style that became a featured layer on openstreetmap.org. Fork when you need a sustained, governed alternative map; for palette and emphasis changes, edit the standard style's variables and rules instead.
Can CartoCSS style vector tiles?
No. CartoCSS belongs to the raster tradition and compiles to Mapnik configuration. Vector tile styling uses a separate style document consumed by renderers such as MapLibre, covered by this site's vector tiles guide.
Photo credits: Pavel Danilyuk (Pexels); Huy Nguyễn (Pexels). Photos are served from this site; follow the credit to the library page for the original.