Osm2pgsql has one program, the executable itself, which has 44 command line
options. A full list of options can be obtained with
osm2pgsql -h -v. This
document provides an overview of options, and more importantly, why you might
--createspecify if osm2pgsql is conducting a new import or adding to an existing one.
--slimis required with
--input-readerspecifies the format if the filetype can't be automatically detected for some reason.
--outputspecifies if the output backend is the default
gazetteeroutput used by Nominatim, the new
multibackend which allows more customization of tables, or
null, which emits no output to the backend.
nullwill create slim tables if
--slimis also used.
Performance is heavily influenced by other options, but there are some options that only impact performance.
--cachespecifies how much memory to allocate for caching information. In
--slimmode, this is just node positions while in non-slim it has to store information about ways and relations too. The maximum RAM it is useful to set this to in slim mode is 8 bytes * number of nodes / efficiency, where efficiency ranges from 50% on small imports to 80% for a planet.
--number-processessets the number of processes to use. This should typically be set to the number of CPU threads, but gains in speed are minimal past 8 threads.
--disable-parallel-indexingdisables the clustering and indexing of all tables in parallel. This reduces disk and ram requirements during the import, but causes the last stages to take significantly longer.
--cache-strategysets the cache strategy to use. The defaults are fine here, and optimized uses less RAM than the other options.
osm2pgsql supports standard options for how to connect to PostgreSQL. If left
unset, it will attempt to connect to the default database (usually the username)
using a unix socket. Most usage only requires setting
--tablespace options allow the location of main and slim tables and indexes
to be set to different tablespaces independently, typically on machines with
multiple drive arrays where one is not large enough for all of the database.
--flat-nodes specifies that instead of a table in PostgreSQL, a binary
file is used as a database of node locations. This should only be used on full
planet imports or very large extracts (e.g. Europe) but in those situations
offers significant space savings and speed increases, particularly on
mechanical drives. The file takes approximately 8 bytes * maximum node ID, or
about 23 GiB, regardless of the size of the extract.
--unlogged specifies to use unlogged tables which are dropped from the
database if the database server ever crashes, but are faster to import.
--prefix specifies the prefix for tables
--slimcauses the middle layer to store node and way information in database rather than in memory. It is required for updates and for large extracts or the entire planet which will not fit in RAM.
--dropdiscards the slim tables when they are no longer needed in the import, significantly reducing disk requirements and saving the time of building slim table indexes. A
--slim --dropimport is generally the fastest way to import the planet if updates are not required.
Output columns options
--extra-attributescreates pseudo-tags with OSM meta-data like user, last edited, and changeset. These also need to be added to the style file.
--stylespecifies the location of the style file. This defines what columns are created, what tags denote areas, and what tags can be ignored. The default.style contains more documentation on this file.
--tag-transform-scriptsets a Lua tag transform to use in place of the built-in C tag transform.
Hstore is a PostgreSQL data type
that allows storing arbitrary key-value pairs. It needs to be installed on
the database with
CREATE EXTENSION hstore;
osm2pgsql has five hstore options
-kadds any tags not already in a conventional column to a hstore column. With the standard stylesheet this would result in tags like highway appearing in a conventional column while tags not in the style like
lanes:forwardwould appear only in the hstore column.
-jadds all tags to a hstore column, even if they're already stored in a conventional column. With the standard stylesheet this would result in tags like highway appearing in conventional column and the hstore column while tags not in the style like
lanes:forwardwould appear only in the hstore column.
-z, which adds an additional column for tags starting with a specified string, e.g.
--hstore-column 'name:'produces a hstore column that contains all
--hstore-match-onlymodifies the above options and prevents objects from being added if they only have tags in the hstore column and no conventional tags.
--hstore-add-indexadds a GIN index to the hstore columns. This can speed up arbitrary queries, but for most purposes partial indexes will be faster.
--hstore-all when combined with
should give the same rows as no hstore, just with the additional hstore column.
Hstore is used to give more flexibility in using additional tags without reimporting the database, at the cost of a less speed and more space.
--projare used to specify the projection used for importing. The default,
--mercis typically used for rendering, while
--latlongcan offer advantages for analysis. Most stylesheets assume
--merchas been used.
Output data options
--multi-geometryskips an optimization for rendering where PostGIS MULTIPOLYGONs are split into multiple POLYGONs.
--multi-geometrycan be used to avoid some labeling issues at the cost of speed. It is also typically required for analysis.
--keep-coastlinesdisables a hard-coded rule that would otherwise discard