Add pgvector to an existing Alpine Postgres

If your stack already runs postgres:16-alpine or postgres:17-alpine and you want the vector extension for embeddings, build pgvector into the same Alpine image rather than switching images.

Why not switch to the pgvector image

The pgvector/pgvector image is based on Debian, which uses glibc. The Alpine images use musl. The two C libraries sort text differently under locales such as en_US.utf8, so starting an existing Alpine data directory under the Debian image changes the order every text index expects. Those indexes then need a full REINDEX, and until they get one they can silently return wrong results. Building pgvector into the Alpine image keeps the data directory’s collation as it is.

Build the image

The package repository ships a Dockerfile for this in docker/pgvector-alpine/:

ARG PG_MAJOR=16
FROM postgres:${PG_MAJOR}-alpine
ARG PGVECTOR_VERSION=v0.8.6
RUN apk add --no-cache --virtual .build-deps git build-base \
 && git clone --depth 1 --branch ${PGVECTOR_VERSION} https://github.com/pgvector/pgvector.git /tmp/pgvector \
 && make -C /tmp/pgvector OPTFLAGS="" with_llvm=no \
 && make -C /tmp/pgvector install with_llvm=no \
 && rm -rf /tmp/pgvector \
 && apk del .build-deps

Build it for the major version your data directory already uses:
Terminal window
```
docker build --build-arg PG_MAJOR=16 -t postgres-pgvector:16-alpine .
```
Point the stack’s Postgres service at the new image, keeping the same volume:
```
services:
  myapp-postgres:
    image: postgres-pgvector:16-alpine
```
Create the extension once, as a superuser or the database owner, or let a migration do it:
```
CREATE EXTENSION IF NOT EXISTS vector;
```

with_llvm=no skips the LLVM bitcode used for JIT inlining. The base images’ Postgres was built with a clang version Alpine no longer ships, so that step fails; pgvector itself builds with gcc and works normally.

Tested on 2026-09-30 with pgvector v0.8.6 on postgres:16-alpine and postgres:17-alpine: the extension loads, and an HNSW vector_cosine_ops index is used for ORDER BY embedding <=> ... queries.