# postgis/docker-postgis: Choosing and Running a Spatial Database Image

> postgis/docker-postgis packages PostgreSQL with PostGIS for teams that need spatial data capabilities in containers. Its main adoption concerns are tag selection, storage-path changes in PostgreSQL 18, and the deliberate restraint of Debian dependency versions.

**postgis/docker-postgis** — Docker image for PostGIS

- Repository: https://github.com/postgis/docker-postgis
- Website: https://hub.docker.com/r/postgis/postgis/
- Stars: 1,603 · Forks: 486
- Language: Dockerfile
- License: MIT
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/postgis-docker-postgis

## What postgis/postgis Adds to the Official postgres Image

postgis/postgis is intended for developers and operators who need spatial queries, geometry data, and related PostgreSQL extensions without assembling the database image and geospatial dependencies separately. It extends the official `postgres` image rather than replacing PostgreSQL with a separate database server. The available Debian and Alpine variants cover combinations of PostgreSQL 14 through 18 and PostGIS 3.5 or 3.6, according to the README.

The image also handles database initialization. The repository says its initialization process installs `postgis`, `postgis_topology`, and, for PostGIS versions below 3.7, `postgis_tiger_geocoder` in the default database. This matters because the default database is not always named `postgres`. Without `POSTGRES_DB`, it takes the name of the administrative user set through `POSTGRES_USER`; if neither is customized, the README identifies that user as `postgres`.

Several packaged extensions remain available without being initialized automatically. These include `postgis_raster`, `postgis_sfcgal`, `address_standardizer`, and `address_standardizer_data_us`. The distinction between installed and initialized packages is important for engineers writing migrations: availability in the image does not mean the extension will already exist in a newly created database. The README also provides a `template_postgis` database for deployments that prefer the older template database mechanism.

## Debian and Alpine Variants Make Different Dependency Choices

The Debian and Alpine lines solve the same packaging problem with different trade-offs. The repository recommends Debian images for new users and describes their release cycle as cautious. Those images install PostGIS, GEOS, PROJ, GDAL, and SFCGAL through Debian packages, which can mean that their dependency versions are not the newest available. For PostgreSQL 14 through 17 on Debian Bullseye, the README lists GEOS 3.9, GDAL 3.2, PROJ 7.2, and SFCGAL 1.3.9. PostgreSQL 18 images use Debian Trixie and list GEOS 3.13, GDAL 3.10, PROJ 9.6, and SFCGAL2 2.0.

The Alpine variants use Alpine Linux 3.24 with musl libc. PostGIS is compiled from source there, while the README lists GEOS 3.14.1, GDAL 3.13.0, PROJ 9.8.1, and SFCGAL 2.2.0. This produces newer listed library versions in the documented examples, but it also makes the Alpine image more challenging to extend according to the README.

That distinction should drive image selection. A team validating spatial results against a particular GEOS, GDAL, or PROJ release can inspect the documented version matrix. A team that expects to install additional operating-system packages may prefer the more established Debian extension path. Neither family removes the need to test the exact application against the selected tag, because PostGIS, PostgreSQL, and native spatial libraries participate in the same runtime.

## Selecting a Versioned postgis/postgis Tag

The README gives two recommended starting points: `postgis/postgis:18-3.6` and `postgis/postgis:17-3.5`. The first pairs PostgreSQL 18 with PostGIS 3.6 and uses Debian Trixie. The second pairs PostgreSQL 17 with PostGIS 3.5 and uses Debian Bullseye. The repository Makefile separately defines `17-3.5` as `LATEST_VERSION`, but that build setting should not be confused with the README's broader recommendation of both tags for new users.

Explicit tags are preferable for reproducible deployment because the repository publishes many combinations spanning operating systems and version lines. The Debian table includes PostgreSQL 14 through 17 with PostGIS 3.5.2, plus PostgreSQL 18 with PostGIS 3.6.4. The Alpine table includes PostGIS 3.5.7 across PostgreSQL 14 through 17 and PostGIS 3.6.4 for PostgreSQL 17 and 18.

Master-branch images are a separate category. The README states that PostgreSQL 17 and 18 variants are tagged `17-master` and `18-master`, with PostGIS and dependencies built from their respective master branches. It also describes alpha, beta, release candidate, and development images. Those labels communicate release status and should not be substituted for a versioned image merely to obtain the newest code.

The documented architecture support is narrower than the tag list may initially suggest: the README states that supported architecture is `amd64` (x86-64). A deployment targeting another processor architecture needs a different image or build path, but the README does not document one.

## PostgreSQL 18 Changes the Container Storage Contract

The largest operational change is not a PostGIS feature. It is the default `VOLUME` path in PostgreSQL 18-based images, which changed to `/var/lib/postgresql`. The documented PostgreSQL 17 default image retains the legacy path `/var/lib/postgresql/data`. A container may appear to run normally while an existing deployment loses access to its data if an orchestration file continues to mount the old location for a PostgreSQL 18 image.

This is a genuine migration constraint. Engineers moving from the recommended PostgreSQL 17 default image to `postgis/postgis:18-3.6` must inspect every volume declaration, bind mount, backup script, and restore procedure that names `/var/lib/postgresql/data`. The repository does not provide a migration command for relocating an existing data directory, so the review cannot be reduced to changing the image tag.

The image also inherits the parent PostgreSQL image's startup environment. The README explicitly documents `POSTGRES_DB` and `POSTGRES_USER`, as well as database naming behavior. It does not document authentication, health-check, replica setup, or orchestration commands for this image. Those concerns need to come from the selected deployment system and the official `postgres` image documentation rather than assumptions about this repository.

## Starting with the Docker Hub Image and Its Initialization Rules

The project directs users to Docker Hub for its published tags and does not provide a `docker pull` or `docker run` example in the README. It would be misleading to invent a startup command, port mapping, password value, or volume mount and present it as a project-supported tutorial. The first deployment step that can be stated exactly is to obtain the image from the `postgis/postgis` Docker Hub page and choose an explicit tag from the documented version table.

For a first real use, configure the PostgreSQL startup variables required by the official image rather than assuming that the image invents a database name. Set `POSTGRES_DB` when a stable application database name is required. Set `POSTGRES_USER` when the administrative account should differ from `postgres`. On the first initialization, the repository's script should create `postgis`, `postgis_topology`, and the applicable Tiger Geocoder extension in that default database.

Before connecting an application, determine which additional extensions the schema actually requires. `postgis_raster`, `postgis_sfcgal`, and the address standardizer packages are available but are not initialized by default. If the application depends on one of them, its database migration must enable the relevant extension. For PostGIS 3.7 and later, `postgis_tiger_geocoder` is no longer provided by PostGIS according to the README, so an application using Tiger Geocoder cannot treat that extension as universal across these image lines.

Persistent storage must also be configured before real data is written. PostgreSQL 18-based tags use `/var/lib/postgresql`, while the documented PostgreSQL 17 default image uses `/var/lib/postgresql/data`. The repository does not document backup scheduling or rollback, so those procedures require separate design.

## Maintenance, Licensing, and the Cost of Changing Versions

The repository is not archived, and its last push was on 2026-06-19. That date indicates recent repository activity, but it does not guarantee that every individual tag will receive fixes at the same cadence. The README describes a cautious Debian release cycle and multiple stable, prerelease, and master image categories. There are also no GitHub releases, so operators should use the repository and Docker Hub tag information rather than expecting a GitHub release history to define the upgrade path.

An upgrade can involve more than changing the PostgreSQL major version. Dockerfiles are organized by version, OS base, and variant. Native spatial dependency versions vary across Debian Bullseye, Debian Trixie, and Alpine 3.24. PostGIS initialization differs between 3.5, 3.6, and images tracking PostGIS 3.7 or later. PostgreSQL 18 also changes the data volume path. These factors create migration work involving SQL compatibility, extension availability, data storage, native library behavior, and application expectations.

The repository is licensed under MIT. That identifies the project's stated licensing model, but image users still need to account for the terms of PostgreSQL, PostGIS, and included operating-system and native packages as part of their own compliance review. The README does not provide a legal interpretation or a consolidated dependency license report.

## When postgis/postgis Is the Wrong Container Choice

postgis/postgis is a poor fit for a deployment that requires an architecture other than the documented `amd64` support. It is also unsuitable when the operating requirement is to track current Debian branches for every geospatial dependency, because the README explicitly warns that GEOS, PROJ, GDAL, and SFCGAL may lag behind. Teams needing predictable native-library versions should select from the matrix rather than choosing a generic tag.

The image is not a complete platform for database administration. The repository does not document backup orchestration, monitoring, replication, restore procedures, or production deployment manifests. Nor does it document automated creation of every optional extension. A service expected to provide those controls should treat the container as the database runtime, not as the entire operational system.

A real alternative is to build a controlled image from the official `postgres` image and add a pinned PostGIS package set and initialization script under the team's own Dockerfile and update policy. That approach requires more assembly work, but it gives direct control over base image, package versions, extension initialization, labels, and internal build process. postgis/postgis is preferable when the maintained version matrix already matches the application and its supported deployment model; a custom image is more relevant when those constraints do not line up.

## Conclusion

Adopt postgis/postgis when an application needs PostgreSQL and PostGIS together as a container, particularly when an explicit versioned tag fits its deployment policy. Do not adopt it if it needs an unsupported architecture, persistent extension setup beyond the documented defaults, or the newest GEOS, PROJ, GDAL, and SFCGAL package versions in Debian-based images. Before deployment, verify the PostgreSQL and PostGIS versions, select Debian or Alpine deliberately, confirm whether extensions must be enabled manually, and match the volume mount to /var/lib/postgresql for PostgreSQL 18 or /var/lib/postgresql/data for the documented PostgreSQL 17 default image.

## FAQ

### Which postgis/postgis image should a new PostgreSQL deployment use?

The README recommends `postgis/postgis:18-3.6` or `postgis/postgis:17-3.5`. The former uses `/var/lib/postgresql`, while the latter uses `/var/lib/postgresql/data`.

### Does postgis/postgis initialize every available PostGIS extension automatically?

No. It initializes `postgis`, `postgis_topology`, and `postgis_tiger_geocoder` for PostGIS below 3.7. Extensions such as `postgis_raster`, `postgis_sfcgal`, and the address standardizer packages remain available but are not initialized by default.

### Which processor architectures does postgis/postgis support?

The README documents `amd64` (x86-64) as the supported architecture. It does not document alternative architecture images in the available guidance.

## Sources

- [Issues](https://github.com/postgis/docker-postgis/issues)
- [License: MIT](https://github.com/postgis/docker-postgis/blob/master/LICENSE)
- [postgis/docker-postgis on GitHub](https://github.com/postgis/docker-postgis)
- [Project website](https://hub.docker.com/r/postgis/postgis/)
- [README](https://github.com/postgis/docker-postgis/blob/master/README.md)

---

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