Upgrade notes


marker-placement now defaults to ‘point’

In TileMill >= 0.10.0 marker placement now defaults to point which means that markers applied to line geometries will no longer automatically be placed along lines or oriented an line angles. For example, arrows will now all point a constant direction. To achieve the previous default behavior, you now need to be explicit and set the placement type to line like:

marker-placement: line;

Buffer size moved from application wide setting to style property

In TileMill >= 0.10.0 you can now control the map buffer-size value in each project by setting it in your CartoCSS alongside other Map level properties like:

Map {
  background-color: #b8dee6;

If you do not set the buffer-size in your CartoCSS it will default to 128 (pixels). Note: For maps using no labels or purely raster data you can get away without any tiling artifacts and improve performance of rendering by setting buffer-size:0.

More concise and powerful CartoCSS syntax for expressions and transforms


Properties like text-name, text-orientation, shield-name, marker-width, marker-height and building-height are all expressions in CartoCSS and Mapnik meaning that they are dynamically evaluated at render time and support math and string operators as well as attribute lookups. Now you can avoid having to quote these property values. For example, previously you needed to do text-name:"'This is: ' + [NAME]"; but now a clearer syntax is supported like text-name:'This is: ' + [NAME];. For properties like marker-width or building-height previously you could only provide bare numbers like marker-width:2 but now you can provide expressions like marker-width:2*[FIELD1]/[FIELD2].


Properties like marker-transform support using svg matrix transformations to scale or rotate image and svg symbols. Previously you needed to pass strings like marker-transform:"scale(2,2)"; but now you can chain functions like marker-transform:rotate(45,0,0),scale(2,2); and you can also use attribute values instead of static values. For instance if you want to rotate based on some field value you can do: marker-transform:rotate([FIELD],0,0);

Data attributes table icon changed

To access a layers data attributes there is now a new grid icon: grid icon

The magnifying glass icon now allows you to zoom to a layer’s extent instead of accessing the data attributes table.

PostGIS extent field now fancy

The PostGIS extent field now supports auto calculating and caching (upon layer save) of the extents for a given layer. This will help automatically speed up rendering for maps using large PostGIS tables. Previously the extent field was a simple input field and if left blank the extent would be calculated dynamically by Mapnik after each layer save and in the background multiple times per project save leading to very slow initial rendering times and map refresh. This could be avoided by hardcoding the extent manually but the new option now avoids having to do this by automatically calculating the right values for you.

raster-mode renamed

Due to changes in Mapnik the raster-mode property is now called raster-comp-op because it supports a wider range of compositing operations and to be consistent with other new styling properties that also support the same operations (like polygon-comp-op or line-comp-op). Also any values for this mode that previously used _ characters like grain_merge now consistenly use - so please use grain-merge instead. For the entire list of supported options please see the built in Carto reference. The default for this property, if not set, is raster-comp-op:src-over which triggers normal alpha blending.

marker-opacity now impacts both fill and stroke

Marker rendering in Mapnik now more properly behaves like SVG rendering meaning that you can now control the opacity of both the fill (marker-fill-opacity) and stroke (marker-line-opacity) independently, and you can set an overall opacity (marker-opacity). Previously marker-opacity only impacted the fill.

Node.js version

Those users who have been using source installs, or were otherwise tracking the Node.js version used and required by TileMill, should be aware that TileMill 0.10.0 works with both Node v0.6.x and v0.8.x. The Windows and Ubuntu packages depend on v0.8.x while the Mac app still uses Node v0.6.x due to this bug.


Plugin Compatibility

An upgraded ModestMaps version included in TileMill 0.9.1 means that some plugins may need to be upgraded (by uninstalling and then re-installing), otherwise glitches in the map UI may be present.

Dropped support for 32-only Macs

For OS X, TileMill 0.9.1 now is only 64-bit (rather than a Universal binary). This will mean that older Macs that only support 32-bit applications (i.e. Macs older than late 2006) will not work - you will see an error message upon startup.

Marker Size

For projects using marker-width or marker-height, these values now need to be twice as large in order to maintain the same visual rendering size as previous TileMill versions. Projects will need to be manually upgraded and we apologize if this is inconvenient. Previously these values represented radii, but should have been pixels, and this bug was fixed upstream in the Mapnik version now required by TileMill.

text-name syntax

The proper syntax for referencing a label field is to enclose the field name in brackets like: text-name: "[field]". The syntax of text-name:"field" previously worked and issued deprecation warnings in the TileMill logs, but this support has now been removed (upstream in Mapnik). If you use the old, now invalid deprecated syntax, you will see an error like: in node TextSymbolizer: Failed to parse expression: "field" in TextSymbolizer.

Node.js version

Those users who have been using source installs, or were otherwise tracking the Node.js version used and required by TileMill, should be aware that TileMill now depends upon Node v0.6.x (previously v0.4.x).

Windows Start Menu and Shortcuts

While TileMill 0.9.0 used a Start Menu shortcut pointed at a .bat file, TileMill 0.9.1 now creates a Shortcut pointing at an .exe named ‘TileMill.exe’, which controls starting the application. If you created desktop shortcuts previously you will need to recreate them using the new items in the Start Menu.


The tile server now runs on its own port (by default port 20008), separate from the port used by the main application (port 20009).


Location of preferences

TileMill settings are now located at ~/.tilemill/config.json. If you are running TileMill as an Ubuntu service, this file will be located at /usr/share/mapbox/.tilemill/config.json. You must manually copy any customized settings to this location before starting TileMill.

Port change

The default port changed from 8889 to 20009. You can update any bookmarks or override this setting by adding the port option in ~/.tilemill.json.


Remote network access

In TileMill 0.6 connections are now only accepted from the loopback interface by default. This prevents users from unknowingly sharing projects with remote users. On Mac OS X, this setting can be changed in the preferences window. On Ubuntu, this setting can be changed by setting the listenHost option in your ~/.tilemill.json file to

Upgrading on Ubuntu

The Mapbox PPA now includes its own packages for nodejs. You must remove the chris-lea nodejs PPA from your sources list and uninstall nodejs before upgrading TileMill. Refer to this issue for more information.

To remove the previous nodejs packages run:

sudo apt-get remove nodejs
sudo rm /etc/apt/sources.list.d/chris-lea-node_js-*.list

To upgrade TileMill run:

sudo apt-get update
sudo apt-get install tilemill libmapnik

Application data directory on Ubuntu

On Ubuntu, TileMill files are now kept in ~/Documents/MapBox by default. You can start TileMill from the Applications menu or Launcher while logged in as a desktop user. After starting TileMill for the first time the aforementioned directory will be created. You may move your projects and other data from their old location, such as /usr/share/mapbox, to the new directory.

Execution changes on Ubuntu

TileMill can now be run as the logged in desktop user on Ubuntu. Look for the TileMill menu item in the Applications menu or Launcher. You may need to adjust file permissions and ownership on your data files to make them readable by TileMill if you decide to move your data from the previous directory (/usr/share/mapbox). You can still run TileMill as a service using the upstart command, if so desired.


Important note for Ubuntu users

A specific version of mapnik is provided in the mapbox PPA for use with TileMill 0.4.x. TileMill will not work if you have any other version of mapnik installed on your system. Please remove any previous versions of mapnik that you may have installed from source or from the mapnik nightly-trunk PPA.

Removing mapnik compiled from source

Enter the directory of the original mapnik source.

cd /home/ubuntu/mapnik # or the path to your mapnik source
sudo make uninstall

Removing mapnik from the nightly-trunk PPA

First remove your mapnik packages.

sudo apt-get uninstall mapnik*

Remove the sources.list entries for the nightly-trunk PPA and run

sudo apt-get update

You can now install TileMill using the install-tilemill.sh script.

Project files

TileMill on Mac OS X now keeps its files in your user’s home directory at ~/Documents/MapBox. On Ubuntu, TileMill files are kept in /usr/share/mapbox. After starting TileMill for the first time the directory will be created. Move your projects from their old location to the new project directory.

Relative paths

If you bravely used relative paths to reference markers and other images in your old Carto stylesheets you need to update the paths to be relative to your project’s directory. For example the following rule which worked in TileMill 0.3.x by virtue of being relative to the Mapnik XML file written into the hidden .cache directory

polygon-pattern-file: url(../project/new-world/res/land.png);

Should be changed to be relative to the project directory

polygon-pattern-file: url(res/land.png);

Minimal mode

A setting for entering and leaving minimal mode no longer exists. Projects will automatically update if you decide to edit their mml and mss files directly with another text editor. Beware that altering projects in both the TileMill UI and your editor is not recommended - TileMill will always give preference to an external editor if changes are made.