Skip to content
Branch: master
Find file Copy path
Find file Copy path
8 contributors

Users who have contributed to this file

@pnorman @lonvia @joto @WillieMaddox @nicolas17 @MaxSem @apmon @DerDakon
260 lines (258 sloc) 11.1 KB
.TH OSM2PGSQL 1 "February 5, 2017"
.\" Please adjust this date whenever revising the manpage.
osm2pgsql \- Openstreetmap data to PostgreSQL converter.
.B osm2pgsql
.RI [ options ] " planet.osm"
.B osm2pgsql
.RI [ options ] " planet.osm.{gz,bz2,pbf}"
.B osm2pgsql
.RI [ options ] " file1.osm file2.osm file3.osm"
This manual page documents briefly the
.B osm2pgsql
.B osm2pgsql
imports data from OSM file(s) into a PostgreSQL database
suitable for use by the Mapnik renderer or the Nominatim geocoder.
OSM planet snapshots can be downloaded from Partial planet files
("extracts") for various countries are available, see
Extracts in PBF (ProtoBufBinary) format are also available from
When operating in "slim" mode (and on a database created in "slim" mode!),
.B osm2pgsql
can also process OSM change files (osc files), thereby bringing an existing
database up to date.
These programs follow the usual GNU command line syntax, with long
options starting with two dashes (`\-').
A summary of options is included below.
Add the OSM file into the database without removing
existing data.
Apply a bounding box filter on the imported data.
Must be specified as: minlon,minlat,maxlon,maxlat
e.g. \fB\-\-bbox\fR \fB\-0.5,51.25,0.5,51.75\fR
Remove existing data from the database. This is the
default if \fB\-\-append\fR is not specified.
\fB\-d\fR|\-\-database name
The name of the PostgreSQL database to connect to.
\fB\-i\fR|\-\-tablespace\-index tablespacename
Store all indices in a separate PostgreSQL tablespace named by this parameter.
This allows one to e.g. store the indices on faster storage like SSDs.
\fB\ \fR\-\-tablespace\-main\-data tablespacename
Store the data tables (non slim) in the given tablespace.
\fB\ \fR\-\-tablespace\-main\-index tablespacename
Store the indices of the main tables (non slim) in the given tablespace.
\fB\ \fR\-\-tablespace\-slim\-data tablespacename
Store the slim mode tables in the given tablespace.
\fB\ \fR\-\-tablespace\-slim\-index tablespacename
Store the indices of the slim mode tables in the given tablespace.
Store data in degrees of latitude & longitude.
Store data in proper spherical Mercator (the default).
\fB\-E\fR|\-\-proj num
Use projection EPSG:num
\fB\-p\fR|\-\-prefix prefix_string
Prefix for table names (default: planet_osm).
\fB\-r\fR|\-\-input\-reader format
Select format of the input file. Available choices are \fBauto\fR
(default) for autodetecting the format,
\fBxml\fR for OSM XML format files, \fBo5m\fR for o5m formatted files
and \fBpbf\fR for OSM PBF binary format.
Store temporary data in the database. Without this mode, all temporary data is stored in
RAM and if you do not have enough the import will not work successfully. With slim mode,
you should be able to import the data even on a system with limited RAM, although if you
do not have enough RAM to cache at least all of the nodes, the time to import the data
will likely be greatly increased.
\fB\ \fR\-\-drop
Drop the slim mode tables from the database once the import is complete. This can
greatly reduce the size of the database, as the slim mode tables typically are the same
size, if not slightly bigger than the main tables. It does not, however, reduce the
maximum spike of disk usage during import. It can furthermore increase the import speed,
as no indices need to be created for the slim mode tables, which (depending on hardware)
can nearly halve import time. Slim mode tables however have to be persistent if you want
to be able to update your database, as these tables are needed for diff processing.
\fB\-S\fR|\-\-style /path/to/style
Location of the osm2pgsql style file. This specifies which tags from the data get
imported into database columns and which tags get dropped. Defaults to /usr/share/osm2pgsql/
\fB\-C\fR|\-\-cache num
Only for slim mode: Use up to num many MB of RAM for caching nodes. Giving osm2pgsql sufficient cache
to store all imported nodes typically greatly increases the speed of the import. Each cached node
requires 8 bytes of cache, plus about 10% \- 30% overhead. For a current OSM full planet import with
its ~ 3 billion nodes, a good value would be 27000 if you have enough RAM. If you don't have enough
RAM, it is likely beneficial to give osm2pgsql close to the full available amount of RAM. Defaults to 800.
\fB\ \fR\-\-cache\-strategy strategy
There are a number of different modes in which osm2pgsql can organize its
node cache in RAM. These are optimized for different assumptions of the data
and the hardware resources available. Currently available strategies are
\fBdense\fR, \fBchunked\fR, \fBsparse\fR and \fBoptimized\fR. \fBdense\fR assumes
that the node id numbers are densely packed, i.e. only a few IDs in the range are
missing / deleted. For planet extracts this is usually not the case, making the cache
very inefficient and wasteful of RAM. \fBsparse\fR assumes node IDs in the data
are not densely packed, greatly increasing caching efficiency in these cases.
If node IDs are densely packed, like in the full planet, this strategy has a higher
overhead for indexing the cache. \fBoptimized\fR uses both dense and sparse strategies
for different ranges of the ID space. On a block by block basis it tries to determine
if it is more effective to store the block of IDs in sparse or dense mode. This is the
default and should be typically used.
\fB\-U\fR|\-\-username name
Postgresql user name.
Force password prompt.
\fB\-H\fR|\-\-host hostname
Database server hostname or socket location.
\fB\-P\fR|\-\-port num
Database server port.
\fB\-e\fR|\-\-expire\-tiles [min_zoom\-]max\-zoom
Create a tile expiry list.
\fB\-o\fR|\-\-expire\-output /path/to/expire.list
Output file name for expired tiles list.
Specifies the output back\-end or database schema to use. Currently
osm2pgsql supports \fBpgsql\fR, \fBgazetteer\fR and \fBnull\fR. \fBpgsql\fR is
the default output back\-end / schema and is optimized for rendering with Mapnik.
\fBgazetteer\fR is a db schema optimized for geocoding and is used by Nominatim.
\fBnull\fR does not write any output and is only useful for testing or with
\-\-slim for creating slim tables.
Include attributes for each object in the database.
This includes the username, userid, timestamp and version.
Note: this option also requires additional entries in your style file.
Add tags without column to an additional hstore (key/value) column to PostgreSQL tables.
Add all tags to an additional hstore (key/value) column in PostgreSQL tables.
\fB\-z\fR|\-\-hstore\-column key_name
Add an additional hstore (key/value) column containing all tags
that start with the specified string, eg \-\-hstore\-column "name:" will
produce an extra hstore column that contains all name:xx tags
\fB\ \fR\-\-hstore\-match\-only
Only keep objects that have a value in one of the columns
(normal action with \-\-hstore is to keep all objects).
\fB\ \fR\-\-hstore\-add\-index
Create indices for the hstore columns during import.
Normally osm2pgsql splits multi\-part geometries into separate database rows per part.
A single OSM id can therefore have several rows. With this option, PostgreSQL instead
generates multi\-geometry features in the PostgreSQL tables.
Keep coastline data rather than filtering it out.
By default natural=coastline tagged data will be discarded based on the
assumption that post-processed Coastline Checker shape files will be used.
\fB\ \fR\-\-exclude\-invalid\-polygon
OpenStreetMap data is defined in terms of nodes, ways and relations and not in
terms of actual geometric features. Osm2pgsql therefore tries to build postgis
geometries out of this data representation. However not all ways and relations
correspond to valid PostGIS geometries (e.g. self intersecting polygons). By
default osm2pgsql tries to fix these geometries using buffer(0) around the
invalid polygons. With this option, invalid polygons are instead simply dropped
from the database. Even without this option, all polygons in the database should
be valid.
\fB\ \fR\-\-unlogged
Use postgresql's unlogged tables for storing data. This requires PostgreSQL 9.1
or above. Data written to unlogged tables is not written to PostgreSQL's write\-ahead log,
which makes them considerably faster than ordinary tables. However, they are not
crash\-safe: an unlogged table is automatically truncated after a crash or unclean shutdown.
\fB\ \fR\-\-number\-processes num
Specifies the number of parallel processes used for certain operations. If disks are
fast enough e.g. if you have an SSD, then this can greatly increase speed of
the "going over pending ways" and "going over pending relations" stages on a multi\-core
By default osm2pgsql initiates the index building on all tables in parallel to increase
performance. This can be disadvantages on slow disks, or if you don't have
enough RAM for PostgreSQL to perform up to 7 parallel index building processes
(e.g. because maintenance_work_mem is set high).
\fB\ \fR\-\-flat\-nodes /path/to/nodes.cache
The flat\-nodes mode is a separate method to store slim mode node information on disk.
Instead of storing this information in the main PostgreSQL database, this mode creates
its own separate custom database to store the information. As this custom database
has application level knowledge about the data to store and is not general purpose,
it can store the data much more efficiently. Storing the node information for the full
planet requires about 100GB in PostgreSQL, the same data is stored in only ~16GB using
the flat\-nodes mode. This can also increase the speed of applying diff files. This option
activates the flat\-nodes mode and specifies the location of the database file. It is a
single large > 16GB file. This mode is only recommended for full planet imports
as it doesn't work well with small imports. The default is disabled.
Help information.
Add \fB\-v\fR to display supported projections.
Verbose output.
Latlong (\-l) SRS: 4326 (none)
Spherical Mercator (\-m) SRS:3857 +proj=merc +a=6378137 +b=6378137 +lat_ts=0.0 +lon_0=0.0 +x_0=0.0 +y_0=0 +k=1.0 +units=m +nadgrids=@null +no_defs +over
EPSG-defined (\-E) SRS: +init=epsg:(as given in parameter)
.BR proj (1),
.BR postgres (1).
osm2pgsql was written by Jon Burgess, Artem Pavlenko, and other
OpenStreetMap project members.
This manual page was written by Andreas Putzo <>
for the Debian project, and amended by OpenStreetMap authors.
\" LocalWords: hstore multi Openstreetmap ProtoBufBinary
You can’t perform that action at this time.