From OpenStreetMap Wiki
Jump to navigation Jump to search

exclamation mark

Imports and automated edits should only be carried out by those with experience and understanding of the way the OpenStreetMap community creates maps, and only with careful planning and consultation with the local community.
See Import/Guidelines and Automated Edits code of conduct for more information. Imports/automated edits which do not follow these guidelines might be reverted!

ogr2osm is a Python script which converts any OGR supported vector format into .osm or .pbf format, with an emphasis on converting polygon boundaries into relations.

Unlike most (if not all) other scripts, such as shp2osm and polyshp2osm, it can save a processing step by converting from any coordinate system supported by PROJ.4 to the system used by OpenStreetMap, (EPSG:4326).

Using a mechanism known as "translation", the script also allows the conversion of source tags and meta-data into properly formatted OpenStreetMap tags.

The current version is maintained by Roel Derickx, released under a MIT license, and located at github. Its development and documentation are focused on users of Ubuntu >18.04 or other Debian-based system.



Requires the ogr and osr module from the gdal library. (Debian/Ubuntu users will need to install gdal-bin, libgdal-dev and python3-gdal). If you want .pbf output you need to install the protocol buffers as well (Debian/Ubuntu users will need to install libprotobuf-dev, protobuf-compiler and python3-protobuf).

To install

git clone https://github.com/roelderickx/ogr2osm.git
cd ogr2osm
git submodule update --init
pip3 install .

To update ogr2osm:

cd ogr2osm
git pull
git submodule update


The basic usage is the same for all versions.

Run the script without any parameters or with --help to see the usage instructions. By default all attributes in the source file will be added to the resulting OSM file as is, however it can be supplied with a Python-based conversion file (known as a 'translation') to convert the source file's attributes into OSM tags. This allows the user to take full advantage of the Python language for processing attributes, such as fixing abbreviations or capitalization.

Example usage producing my-shapefile.osm, ready to be loaded (i.e. into JOSM).

ogr2osm my-shapefile.shp [-t my-translation-file.py]

See the translations/ directory for sample translation files. The translations for roelderickx's version are kept in the ogr2osm-translations repo and should be automatically downloaded.

How it works

The script has three separate phases: parse, merge, and output.

During the parse phase, the script loops through all the geometries in the OGR datasource and adds them to internal data structures. All lines and polygons get converted into a set of 2-node segments. Duplicated or re-used nodes and segments are detected and treated.

During the merge phase, 2-node segments will be merged into longer chains of nodes. Two adjacent segments or chains will be merged if both of them are members of the same geometries. This algorithm will effectively detect the node chains that are the boundary lines between polygons.

After the merge phase, all lines and polygons will be sets of node chains (ways). Geometries consisting of one way will be output as ways, and geometries consisting of more will be output as relations.

Known issues

Large Datasets

roelderickx's ogr2osm will work on very large files, given enough ram

The original version fails to convert a dataset when it is very big (e.g. a 500MB shapefile). In March 2010 Ivansanchez was reported to be working on a revamped version of ogr2osm that would be much slower (10x) but would hold all the data in a SQLite database instead of in memory.

Running under Windows

This thread http://lists.osgeo.org/pipermail/gdal-dev/2009-December/022992.html highlights a problem with running ogr2osm under Microsoft Windows. It will work with the OSGeo4W shell (download) provided that python-gdal bindings are installed. An easier way to install GDAL and python bindings for running ogr2osm on Windows is to use the Windows binaries from gisinternals.com. It is enough to install GDAL core components and python bindings for the right python version by running the corresponding MSI installer packages. Some people may feel it simpler to use a virtual machine using Ubuntu then to run ogr2osm under Windows.

Dealing with CSV files

Converting CSV files using the GDAL library is not an easy task. csv2osm is a script similar to ogr2osm to convert .csv files to the .osm format. This script allows to specify the columns containing the longitude and latitude information and to translate the columns into proper OpenStreetMap tags using a user-provided Python file, in the same way ogr2osm does.

Upgrading from pnorman's version

In the latest version of ogr2osm the translation file must contain a subclass of ogr2osm.TranslationBase in stead of separate functions to make the code more maintainable. If you are upgrading from pnorman's version and you use a translation file for your data, be sure to read about the modifications you will need to do.


Current Version - MIT License

Original/SVN: "Beerware" -


<ivan@sanchezortega.es> wrote this file. As long as you retain this notice you can do whatever you want with this stuff. If we meet some day, and you think this stuff is worth it, you can buy me a beer in return.


Ogr2osm was created by Iván Sánchez Ortega, his version can be found on the OSM SVN server. It was rewritten by Andrew Guertin (Andrew Guertin's version for UVM) and subsequently maintained by Paul norman (Paul Norman's rewrite of Andrew Guertin's version for UVM). None of these versions is still under active development or maintenance.

External links