# docker-postgis

**Repository Path**: mirrors_postgis/docker-postgis

## Basic Information

- **Project Name**: docker-postgis
- **Description**: Docker image for PostGIS
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2020-08-19
- **Last Updated**: 2026-05-23

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# postgis/postgis

[![Build Status](https://github.com/postgis/docker-postgis/workflows/Docker%20PostGIS%20CI/badge.svg)](https://github.com/postgis/docker-postgis/actions) [![Join the chat at https://gitter.im/postgis/docker-postgis](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/postgis/docker-postgis?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge)

**⚠️ Breaking change (PostgreSQL 18+):**
Default `VOLUME` path changed to `/var/lib/postgresql`

The `postgis/postgis` image provides tags for running Postgres with [PostGIS](http://postgis.net/) extensions installed. This image is based on the official [`postgres`](https://registry.hub.docker.com/_/postgres/) image and provides Debian and Alpine variants for PostGIS 3.5.x and 3.6.x that are compatible with PostgreSQL versions 14, 15, 16, 17 and 18. Additionally, image variants are provided for PostgreSQL 17 and 18, built with PostGIS (and its dependencies) from their respective master branches. These are tagged as `17-master` and `18-master`.

This image ensures that the default database created by the parent `postgres` image will have the following extensions installed:

| installed extensions | [initialized](https://github.com/postgis/docker-postgis/blob/master/initdb-postgis.sh)|
|--------------------------|-----|
| `postgis`                | yes |
| `postgis_topology`       | yes |
| `postgis_tiger_geocoder` | yes, for PostGIS < 3.7 |
| `postgis_raster` | no (available) |
| `postgis_sfcgal` | no (available) |
| `address_standardizer`| no (available) |
| `address_standardizer_data_us`| no (available) |

For PostGIS 3.5 and 3.6 images, `address_standardizer` and `address_standardizer_data_us` are available from the PostGIS package but are not initialized by default. For `*-master` images tracking PostGIS >= 3.7, `address_standardizer` is installed separately from https://github.com/postgis/address_standardizer, while `postgis_tiger_geocoder` is no longer provided by PostGIS.

Unless `-e POSTGRES_DB` is passed to the container at startup time, this database will be named after the admin user (either `postgres` or the user specified with `-e POSTGRES_USER`). If you would prefer to use the older template database mechanism for enabling PostGIS, the image also provides a PostGIS-enabled template database called `template_postgis`.

## Versions (2026-04-16)

Supported architecture: `amd64` (x86-64)

Recommended versions for new users are:

* `postgis/postgis:18-3.6`
  * ⚠️ Uses `VOLUME` path `/var/lib/postgresql` (changed in PostgreSQL 18+)
* `postgis/postgis:17-3.5`
  * Uses legacy `VOLUME` path `/var/lib/postgresql/data`

### Debian based (recommended)

* This Docker-PostGIS image has a cautious release cycle to guarantee high stability.
  * By "cautious", we mean it does not always have the latest versions of geos, proj, gdal, and sfcgal packages.
* We use PostGIS, geos, proj, gdal, and sfcgal packages from the Debian repository.
  * In the Debian Bullseye repository (for PostgreSQL 14 to 17), the versions are:
    * geos=3.9
    * gdal=3.2
    * proj=7.2
    * sfcgal=1.3.9
  * In the Debian Trixie repository (for PostgreSQL 18+), the versions are:
    * geos=3.13
    * gdal=3.10
    * proj=9.6
    * sfcgal2=2.0
* This version is easy to extend and has matured over time.

<!-- debian_autogenerated_begin  -->
<!-- This part is automatically generated by ./update.sh. Do not modify this section manually. -->
| DockerHub image | Dockerfile | OS | Postgres | PostGIS |
| --------------- | ---------- | -- | -------- | ------- |
| [postgis/postgis:14-3.5](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=14-3.5) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/14-3.5/Dockerfile) | debian:bullseye | 14 | 3.5.2 |
| [postgis/postgis:15-3.5](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=15-3.5) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/15-3.5/Dockerfile) | debian:bullseye | 15 | 3.5.2 |
| [postgis/postgis:16-3.5](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=16-3.5) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/16-3.5/Dockerfile) | debian:bullseye | 16 | 3.5.2 |
| [postgis/postgis:17-3.5](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=17-3.5) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/17-3.5/Dockerfile) | debian:bullseye | 17 | 3.5.2 |
| [postgis/postgis:18-3.6](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=18-3.6) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/18-3.6/Dockerfile) | debian:trixie | 18 | 3.6.3 |
<!-- debian_autogenerated_end  -->

### Alpine based

* The base operating system is [Alpine Linux](https://alpinelinux.org/). It is designed to be small, simple, and secure, and it's based on [musl libc](https://musl.libc.org/).
* In the Alpine 3.23 version, the package versions are:
  * geos=3.14.1
  * gdal=3.11.5
  * proj=9.7.1
  * sfcgal=2.2.0
* PostGIS is compiled from source, making it a bit more challenging to extend.

<!-- alpine_autogenerated_begin  -->
<!-- This part is automatically generated by ./update.sh. Do not modify this section manually. -->
| DockerHub image | Dockerfile | OS | Postgres | PostGIS |
| --------------- | ---------- | -- | -------- | ------- |
| [postgis/postgis:14-3.5-alpine](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=14-3.5-alpine) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/14-3.5/alpine/Dockerfile) | alpine:3.23 | 14 | 3.5.6 |
| [postgis/postgis:15-3.5-alpine](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=15-3.5-alpine) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/15-3.5/alpine/Dockerfile) | alpine:3.23 | 15 | 3.5.6 |
| [postgis/postgis:16-3.5-alpine](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=16-3.5-alpine) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/16-3.5/alpine/Dockerfile) | alpine:3.23 | 16 | 3.5.6 |
| [postgis/postgis:17-3.5-alpine](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=17-3.5-alpine) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/17-3.5/alpine/Dockerfile) | alpine:3.23 | 17 | 3.5.6 |
| [postgis/postgis:17-3.6-alpine](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=17-3.6-alpine) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/17-3.6/alpine/Dockerfile) | alpine:3.23 | 17 | 3.6.3 |
| [postgis/postgis:18-3.6-alpine](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=18-3.6-alpine) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/18-3.6/alpine/Dockerfile) | alpine:3.23 | 18 | 3.6.3 |
<!-- alpine_autogenerated_end  -->

### Test images

* We provide alpha, beta, release candidate (rc), and development (identified as ~master) versions.
* For `*-master` images, the template is updated manually, which might lead to a delay of a few weeks sometimes.
* Current PostGIS 3.7 development images use the up-to-date CGAL revision from the `6.1.x-branch`.
* Starting with PostGIS >= 3.7, PostGIS itself no longer includes the `address_standardizer` and `postgis_tiger_geocoder` extensions. The `*-master` images install `address_standardizer` separately from https://github.com/postgis/address_standardizer and run its upstream-style installcheck. See: https://lists.osgeo.org/pipermail/postgis-devel/2026-February/030730.html
* They also install the `h3` and `h3_postgis` extensions from the `main` branch of https://github.com/postgis/h3-pg; because this is a development branch, their extension version may appear as `unreleased`.

<!-- test_autogenerated_begin  -->
<!-- This part is automatically generated by ./update.sh. Do not modify this section manually. -->
| DockerHub image | Dockerfile | OS | Postgres | PostGIS |
| --------------- | ---------- | -- | -------- | ------- |
| [postgis/postgis:17-master](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=17-master) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/17-master/Dockerfile) | debian:trixie | 17 | development: postgis, geos, proj, gdal |
| [postgis/postgis:18-master](https://registry.hub.docker.com/r/postgis/postgis/tags?page=1&name=18-master) | [Dockerfile](https://github.com/postgis/docker-postgis/blob/master/18-master/Dockerfile) | debian:trixie | 18 | development: postgis, geos, proj, gdal |
<!-- test_autogenerated_end  -->

## Usage

In order to run a basic container capable of serving a PostGIS-enabled database, start a container as follows:

```sh
docker run --name some-postgis -e POSTGRES_PASSWORD=mysecretpassword -d postgis/postgis
```

For more detailed instructions about how to start and control your Postgres container, see the documentation for the [postgres image](https://registry.hub.docker.com/_/postgres/).

Once you have started a database container, you can then connect to the database either directly on the running container:

```sh
docker exec -ti some-postgis psql -U postgres
```

... or starting a new container to run as a client. In this case you can use a user-defined network to link both containers:

```sh
docker network create some-network

# Server container
docker run --name some-postgis --network some-network -e POSTGRES_PASSWORD=mysecretpassword -d postgis/postgis

# Client container
docker run -it --rm --network some-network postgis/postgis psql -h some-postgis -U postgres
```

Check the documentation on the [`postgres` image](https://registry.hub.docker.com/_/postgres/) and [Docker networking](https://docs.docker.com/network/) for more details and alternatives on connecting different containers.

See [the PostGIS documentation](http://postgis.net/docs/postgis_installation.html#create_new_db_extensions) for more details on your options for creating and using a spatially-enabled database.

## Supported Environment Variables

Since the docker-postgis repository is an extension of the official Docker PostgreSQL repository, all environment variables supported there are also supported here:

* `POSTGRES_PASSWORD`
* `POSTGRES_USER`
* `POSTGRES_DB`
* `POSTGRES_INITDB_ARGS`
* `POSTGRES_INITDB_WALDIR`
* `POSTGRES_HOST_AUTH_METHOD`
* `PGDATA`  [⚠️ Changed in Docker PostgreSQL >=18 ! ⚠️ ](https://github.com/docker-library/docs/blob/master/postgres/README.md#pgdata )

Read more in the [docker-postgres README page](https://github.com/docker-library/docs/blob/master/postgres/README.md)


### ⚠️ `PGDATA` Volume Path Change

Starting from **PostgreSQL 18**, the default data directory (`VOLUME`) path has changed.
This affects all corresponding **`postgis/postgis:18-*`** and newer images.

**Summary of volume paths:**

| Image name | Image tag range | `--volume` path |
|-------------|-----------------|-----------------|
| `postgis/postgis` | `18-*` … | `/var/lib/postgresql` |
| `postgis/postgis` | `14-*` … `17-*` | `/var/lib/postgresql/data` |

Please adjust your volume mounts for 18+ images.
For more details, see the [upstream change](https://github.com/docker-library/postgres/pull/1259).

### Initialize Only on Empty Data Directory

Docker-specific environment variables (for example, `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`)
take effect **only when the container is started with an empty data directory**.
Any pre-existing database will be left **untouched** on container startup.

If you need to re-initialize or change settings, make sure to remove or re-create the volume first.

### `libpq` Environment Variables

Please note that Docker environment variables are **different** from those used by the
[libpq — C Library](https://www.postgresql.org/docs/current/libpq-envars.html).
These include: `PGDATABASE`, `PGUSER`, `PGPASSWORD`, and others used by client tools.

## Troubleshooting tips

Troubleshooting can often be challenging. It's important to know that the docker-postgis repository is an extension of the official Docker PostgreSQL repository. Therefore, if you encounter any issues, it's worth testing whether the problem can be reproduced with the [official PostgreSQL Docker images](https://hub.docker.com/_/postgres). If so, it's recommended to search for solutions based on this. The following websites are suggested:

* Upstream docker postgres repo: https://github.com/docker-library/postgres
  * search for the open or closed issues !
* Docker Community Forums: https://forums.docker.com
* Docker Community Slack: https://dockr.ly/slack
* Stack Overflow: https://stackoverflow.com/questions/tagged/docker+postgresql

If your problem is PostGIS related:

* Stack Overflow : docker + postgis https://stackoverflow.com/questions/tagged/docker+postgis
* PostGIS issue tracker: https://trac.osgeo.org/postgis/report

And if you don't have a postgres docker experience - read this blog post:

* https://www.docker.com/blog/how-to-use-the-postgres-docker-official-image/

## Security

It's crucial to be aware that in a cloud environment, with default settings, these images are vulnerable, and there's a high risk of cryptominer infection if the ports are left open. ( [Read More](https://github.com/docker-library/postgres/issues/770#issuecomment-704460980) )

* Note that ports which are not bound to the host (i.e., `-p 5432:5432` instead of `-p 127.0.0.1:5432:5432`) will be accessible from the outside. This also applies if you configured UFW to block this specific port, as Docker manages its own iptables rules. ( [Read More](https://docs.docker.com/network/iptables/) )

### io_uring

Every `postgis/postgis:18-*` image includes `io_uring` capabilities for asynchronous I/O.  However, some container runtimes (for example, [containerd](https://github.com/containerd/containerd/issues/9048)) have **disabled `io_uring` support** in the past due to **security concerns**.
If you wish to experiment with this feature, please do so **at your own risk**, and only after explicitly enabling `io_uring` in your [seccomp profile](https://docs.docker.com/engine/security/seccomp/).

### Recommendations

* You can add options for using SSL ( [see postgres example](https://github.com/docker-library/postgres/issues/989#issuecomment-1222648067) )
  * `-c ssl=on -c ssl_cert_file=/var/lib/postgresql/server.crt -c ssl_key_file=/var/lib/postgresql/server.key`
* Or you can use [SSH Tunnels](https://www.postgresql.org/docs/15/ssh-tunnels.html) with `-p 127.0.0.1:5432:5432`

### Security scanner information

* Please also scan the base `postgres` Docker image for potential security issues.
If your security scanner reports vulnerabilities (CVEs), check the [Docker Library FAQ](https://github.com/docker-library/faq#why-does-my-security-scanner-show-that-an-image-has-cves) — especially the section *“Why does my security scanner show that an image has CVEs?”*
For more specific issues related to the Postgres Docker image, you can search using these links:
  * [search for repo:docker-library/postgres trivy](https://github.com/search?q=repo%3Adocker-library%2Fpostgres+trivy&type=issues)
  * [search for repo:docker-library/postgres CVE](https://github.com/search?q=repo%3Adocker-library%2Fpostgres+CVE&type=issues)

* Optimizing Security Scans:
It's advisable to focus on scanning and fixing issues that can be resolved.
Use this command to scan for fixable issues only:
  * `trivy image --ignore-unfixed postgis/postgis:18-3.6-alpine`
  * `trivy image --ignore-unfixed postgres:18-alpine`
For more details, you can read [this article](https://pythonspeed.com/articles/docker-security-scanner/)

## Limitations on Updates

Unfortunately, we don't have control over updates to Debian and Alpine distributions or the upstream `postgres` image.
Because of this, there might be some issues that we cannot fix right away.
On the positive side, the `postgis/postgis` images are regenerated every Monday. This process is to ensure they include the latest changes and improvements. As a result, these images are consistently kept up-to-date.

## Suggestions Welcome

We are always open to suggestions to enhance security. If you have any ideas, please let us know.

## Known Issues / Errors

When you encounter errors due to PostGIS update `OperationalError: could not access file "$libdir/postgis-X.X`, run:

`docker exec some-postgis update-postgis.sh`

It will update to your newest PostGIS. Update is idempotent, so it won't hurt when you run it more than once. You will get a notification like:

```log
Updating PostGIS extensions template_postgis to X.X.X
NOTICE:  version "X.X.X" of extension "postgis" is already installed
NOTICE:  version "X.X.X" of extension "postgis_topology" is already installed
NOTICE:  version "X.X.X" of extension "postgis_tiger_geocoder" is already installed
ALTER EXTENSION
Updating PostGIS extensions docker to X.X.X
NOTICE:  version "X.X.X" of extension "postgis" is already installed
NOTICE:  version "X.X.X" of extension "postgis_topology" is already installed
NOTICE:  version "X.X.X" of extension "postgis_tiger_geocoder" is already installed
ALTER EXTENSION
```

## Contributor guideline

This Docker-PostGIS project [is part of the PostGIS group](https://postgis.net/development/rfcs/rfc05/#projects-under-postgis-umbrella) and follows more flexible contributor rules.

* Please take a moment to review the current issues, discussions, and pull requests before you start.
* If you have a major change in mind, we kindly ask you to start a discussion about it first.
* After making changes to the templates, please run the `./update.sh` script.
* The `README.md` must be written in plain and platform-compatible Markdown that renders correctly on both GitHub and [Docker Hub](https://hub.docker.com/r/postgis/postgis).

## Code of Conduct

Link to [the code of conduct](https://postgis.net/community/conduct/)