# osm2pgsql: importing OpenStreetMap data into PostGIS

> osm2pgsql is a C++ import and update tool for putting OpenStreetMap data into PostgreSQL and PostGIS. It supports several OSM input formats, Lua-controlled table layouts, geographic generalization, and imports ranging from small extracts to planet-scale datasets.

**osm2pgsql-dev/osm2pgsql** — Import OpenStreetMap data into a PostgreSQL/PostGIS database

- Repository: https://github.com/osm2pgsql-dev/osm2pgsql
- Website: https://osm2pgsql.org
- Stars: 1,686 · Forks: 482
- Language: C++
- License: GPL-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/osm2pgsql-dev-osm2pgsql

## What osm2pgsql loads into PostgreSQL and PostGIS

osm2pgsql addresses a specific gap between raw OpenStreetMap data and database-backed geographic applications. It loads OSM data into a PostgreSQL database with PostGIS, creating a spatial data layer that can support map rendering, geocoding workflows associated with Nominatim, and general geographic analysis. The intended users are operators and developers who need control over a PostgreSQL or PostGIS data model rather than only running an application with a fixed schema.

The README describes support for a small geographic area on a laptop through the whole world on a large server. That range does not mean one deployment recipe covers both cases. Database configuration, available memory and storage, processing time, and the amount of imported data still affect individual installations. The project runs on Linux, Windows, and macOS, but the README does not claim identical package availability or installation procedures across all three.

The project is not a general-purpose PostgreSQL ETL package. Its input model is centered on OSM data, and its spatial output is tied to PostGIS. Its Lua processing layer also means that adopting the tool involves deciding how tags should be translated into tables and columns, not merely selecting a destination database. Teams that want a ready-made geocoding interface should inspect Nominatim separately rather than treating osm2pgsql as the complete geocoder.

## OSM inputs, Lua layouts, and PostGIS output

The documented data flow begins with OpenStreetMap data in OSM XML, PBF, or O5M format. osm2pgsql reads that data and writes it into PostgreSQL and PostGIS. The resulting table layout and content can be configured through Lua, which makes schema policy part of the import process rather than a fixed consequence of using the tool.

Lua tag transformations can optionally use LuaJIT on supported platforms. The README says LuaJIT can speed up Lua tag transformations considerably, so it is relevant when processing rules are central to an import and the platform supports it. This is an optional build choice, not part of the default path. Projection support follows a similar pattern. EPSG:4326 and EPSG:3857 are built in, while other projections use the PROJ library when CMake finds it. Setting `WITH_PROJ` to `OFF` disables that library support.

For ongoing data maintenance, osm2pgsql accepts OSM change files and replication diffs for database updates. That capability is distinct from Nominatim. The README lists geocoding with Nominatim as an application that can use the imported database, but it does not say that osm2pgsql implements Nominatim's complete search and indexing service.

The repository layout places implementation and test-related files under `src/`, `tests/`, `cmake/`, and `contrib/`. Lua-related entries include `style.lua`, `default.style`, `empty.style`, and `.luacheckrc`. Based on these files, Lua behavior and database import behavior are first-class parts of the project. A production import should therefore treat the selected Lua layout as an operational asset that needs version control and review, although the README does not prescribe a management policy.

## Installing and building osm2pgsql from source

For a packaged installation, the README says most Linux distributions include osm2pgsql, Debian offers the latest version through backports, macOS provides it through Homebrew, and Windows users can use the project's binary builds. A package is the simpler route when its version and optional features match the target system. The repository points to its installation page for platform-specific instructions.

The following source-build tutorial uses the Debian or Ubuntu dependency command printed in the README. Package availability can vary by distribution release, so operators should confirm that the named development packages exist before running it.

```bash
sudo apt-get install make cmake g++ libboost-dev \
  libexpat1-dev zlib1g-dev libpotrace-dev \
  libopencv-dev libbz2-dev libpq-dev libproj-dev lua5.3 liblua5.3-dev \
  pandoc nlohmann-json3-dev pyosmium
```

The README begins the source workflow by cloning the repository:

```bash
git clone https://github.com/osm2pgsql-dev/osm2pgsql.git
```

From the repository root, create a separate build directory and configure it with CMake:

```bash
mkdir build && cd build
cmake ..
```

A successful configuration should generate the build files expected by CMake. If a dependency is not found, the README says that setting `CMAKE_PREFIX_PATH` to a list of suitable paths is often sufficient. It does not give a universal value because the required paths depend on the host system.

Compile the project after configuration finishes:

```bash
make
```

Install the compiled files after the build completes:

```bash
sudo make install
```

The README does not include a complete first import command containing an input file and database configuration. It directs users to the installation and usage documentation for running osm2pgsql, so an import command should be taken from the documentation for the chosen release rather than assembled from unconfirmed options.

## Verifying LuaJIT and configuring a production build

LuaJIT is optional, but it matters when Lua tag transformations account for a significant part of import work. On Debian or Ubuntu, the README documents installation of the LuaJIT development library:

```bash
sudo apt-get install libluajit-5.1-dev
```

The CMake configuration must then enable `WITH_LUAJIT`:

```bash
cmake -D WITH_LUAJIT=ON ..
```

The README says `osm2pgsql --version` verifies whether the build includes LuaJIT support. Its example output includes a line resembling the following:

```text
Lua 5.1.4 (LuaJIT 2.1.0-beta3)
```

A plain build is different from a debugging or production-oriented build. By default, CMake creates a Release build with debug information and disables tests. The README states that Debug builds are much slower and recommends `Release` or `RelWithDebInfo` for production. A build with tests enabled can be configured as follows:

```bash
cmake .. -G "Unix Makefiles" -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTS=ON
```

Compiler support is bounded. A C++17 compiler is required, and the project officially supports gcc 10.0 or newer and clang 13 or newer. The database requirements are PostgreSQL 12 or newer and PostGIS 3.0 or newer, while PostgreSQL 14 or newer is strongly recommended. Older database deployments therefore need an upgrade or a different package build before they can use the documented source requirements.

## Generalization support and its experimental boundary

osm2pgsql includes experimental support for data generalization. Its feature list also includes building geometries in simple feature format, while OpenCV and potrace appear as optional build dependencies specifically for generalization. This indicates a processing path beyond ordinary geometry construction, but the README does not define supported algorithms, expected accuracy, resource requirements, or compatibility guarantees.

There is also an interaction between schema choice and geometry processing. Lua controls table layout and content, while simple feature construction and generalization affect the spatial representation produced from OSM input. A deployment that needs specific geometric output must consult the dedicated generalization documentation before committing to an import design. The source build requires OpenCV and potrace only when this optional feature is needed.

This is a clear case where osm2pgsql may be the wrong choice. If an application depends on strict cartographic generalization guarantees, the README does not establish that osm2pgsql supplies them. Its explicitly experimental status is the deciding constraint. The same caution applies to deployments that treat imported geometry as fully generalized without first confirming the documented output rules.

For ordinary PostGIS imports, the absence of OpenCV or potrace does not prevent the core source build, according to the dependency list. For generalization workflows, operators must verify both the optional libraries and the behavior documented at the linked generalization pages.

## Packaged binaries compared with source builds

There are two concrete installation paths. Distribution packages, Homebrew on macOS, and the project's Windows binaries delegate dependency resolution to a provider. This is the simpler choice when the available version satisfies the database and feature requirements. It does not, however, create a PostGIS database or select a Lua table layout.

The source path adds CMake, a C++17 compiler, development libraries, and knowledge of the build configuration. In return, operators can control the build type, test status, dependency selection, PROJ integration, LuaJIT, and optional generalization components. That control is useful for reproducible server deployments, but it increases setup work and makes library discovery part of the initial configuration.

The README identifies fmt, libosmium, and protozero as included under `contrib`. Compatible external versions can be selected through the corresponding `EXTERNAL_*libname*` CMake options. Python and Psycopg are test dependencies. OpenCV and potrace remain optional.

No path removes the runtime need for a PostgreSQL server and PostGIS. The package path may also vary by distribution release. Before choosing it, an operator should compare the packaged version with the project release that contains any required options or Lua behavior.

## GPL-2.0 licensing and upgrade considerations

The repository identifies osm2pgsql as free software under version 2 of the GNU General Public License or, optionally, any later version. The README states that redistribution and modification are allowed under those terms. Projects that distribute the software should inspect `COPYING` and account for the applicable notice, source, and licensing obligations. This description identifies the declared license; it is not legal advice.

The repository is not archived. Its last push was on 2026-10-15. Recent releases include version 2.3.1 on 2026-07-05, version 2.3.0 on 2026-06-10, and version 2.2.0 on 2025-09-17. These records show recent release activity, but the README does not document an in-place database migration procedure or automatic compatibility across all three versions.

An upgrade therefore requires a project-specific check. Operators should compare their command-line usage, Lua layouts, imported schema, and optional features with the documentation for the destination release. They should also test whether PostgreSQL and PostGIS satisfy that release's requirements. Recent release dates do not confirm that an existing database can be upgraded without schema or processing changes.

## Conclusion

osm2pgsql is appropriate for engineers who need to build or maintain a custom PostGIS database from OpenStreetMap and can accept responsibility for PostgreSQL, PostGIS, input data, storage design, and Lua processing. It is less suitable for users who only want a prebuilt geocoding service or cannot support a spatial database. Before adoption, verify the supported platform, required database versions, chosen Lua layout, projection, optional generalization dependencies, and package availability for the target system.

## FAQ

### Which input formats can osm2pgsql read?

The README states that osm2pgsql can read OSM, PBF, and O5M formats. It can also update a database from OSM change files and replication diffs.

### What database versions does osm2pgsql require?

The project requires PostgreSQL 12 or newer and PostGIS 3.0 or newer. PostgreSQL 14 or newer is strongly recommended.

### Does osm2pgsql support LuaJIT and custom PostGIS table layouts?

Lua controls table layout and content, while LuaJIT is optional on supported platforms for faster tag transformations. The version output can be checked for LuaJIT support after a build configured with `WITH_LUAJIT=ON`.

## Sources

- [License: GPL-2.0](https://github.com/osm2pgsql-dev/osm2pgsql/blob/master/LICENSE)
- [osm2pgsql-dev/osm2pgsql on GitHub](https://github.com/osm2pgsql-dev/osm2pgsql)
- [Project website](https://osm2pgsql.org)
- [README](https://github.com/osm2pgsql-dev/osm2pgsql/blob/master/README.md)
- [Releases](https://github.com/osm2pgsql-dev/osm2pgsql/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/osm2pgsql-dev-osm2pgsql