100% working container for Nominatim.
The easiest way to use Nominatim Docker is by pulling the pre-built images from Docker Hub.
To quickly get a Nominatim instance up and running with a small dataset (e.g., Monaco):
docker run -it \
-e PBF_URL=https://download.geofabrik.de/europe/monaco-latest.osm.pbf \
-p 8080:8080 \
--name nominatim \
mediagis/nominatim:5.2After the import is complete, you can access the Nominatim API at http://localhost:8080/search?q=avenue%20pasteur.
To use an external PostgreSQL database instead of the in-container database, provide the following environment variables:
docker run -it \
-e PGHOST=your-rds-endpoint.rds.amazonaws.com \
-e PGPORT=5432 \
-e PGDATABASE=nominatim \
-e PGUSER=nominatim \
-e PGPASSWORD=your-password \
-e PBF_URL=https://download.geofabrik.de/europe/monaco-latest.osm.pbf \
-p 8080:8080 \
--name nominatim \
mediagis/nominatim:5.2When PGHOST is set, the container will:
- Test the database connection immediately before downloading any data (fail fast)
- Not start the in-container PostgreSQL service
- Use the external database for all operations
- Automatically use SSL encryption for AWS RDS connections (password auth, not client certificates)
- Verify PostGIS extension is installed and available
- Assume the database and users already exist (you must create them beforehand)
SSL Configuration:
The container uses password authentication with SSL encryption (PGSSLMODE=require), not client certificate authentication. This is the standard configuration for AWS RDS. The AWS CA bundle is automatically used to verify the server's identity.
Connection Testing: The container tests the PostgreSQL connection before downloading any OSM/PBF files. If the connection fails, it will exit immediately with an error message explaining what to check. This prevents wasting time and bandwidth on downloads when the database isn't accessible.
Prerequisites for external database:
- PostgreSQL 16 with PostGIS extension installed
- Database named according to
PGDATABASE(default:nominatim) - User with superuser privileges during import
- For AWS RDS: Database parameter group must have
postgisextension enabled
The service includes a health check endpoint at /health that always returns HTTP 200 with service status:
curl http://localhost:8080/healthResponse:
{"status":"online","service":"nominatim"}You can pull specific versions of the Nominatim Docker image by specifying the tag. For example, to use Nominatim version 5.2:
docker pull mediagis/nominatim:5.2For a list of available tags, please refer to the Docker Hub page.
For information regarding the latest supported security version and security policies for Nominatim, please refer to the official Nominatim security documentation: Nominatim Security Policy.
For comprehensive instructions on advanced configuration, importing custom PBF files, persistent data, updating the database, PostgreSQL tuning, and more, please refer to the detailed how-to guide.
It is the goal of this project to provide and easy to use container image that runs all services in a single container. The downside is that this makes the Dockerfile quite complex and harder to modify.
If you're looking for a project which separates the individual concepts into separate containers, check out https://github.com/smithmicro/n7m.
Thanks goes to these wonderful people (emoji key):
This project follows the all-contributors specification. Contributions of any kind welcome!