Skip to content

Installation Notes

Jump to bottom
andreiramani edited this page May 20, 2026 · 1 revision

Installation Notes - Linux and Mac

Postgres Location

If your machine has multiple Postgres installations, specify the path to pg_config with:

export PG_CONFIG=/Library/PostgreSQL/18/bin/pg_config

Then re-run the installation instructions (run make clean before make if needed). If sudo is needed for make install, use:

sudo --preserve-env=PG_CONFIG make install

A few common paths on Mac are:

  • EDB installer - /Library/PostgreSQL/18/bin/pg_config
  • Homebrew (arm64) - /opt/homebrew/opt/postgresql@18/bin/pg_config
  • Homebrew (x86-64) - /usr/local/opt/postgresql@18/bin/pg_config

Note: Replace 18 with your Postgres server version

Missing Header

If compilation fails with fatal error: postgres.h: No such file or directory, make sure Postgres development files are installed on the server.

For Ubuntu and Debian, use:

sudo apt install postgresql-server-dev-18

Note: Replace 18 with your Postgres server version

Missing SDK

If compilation fails and the output includes warning: no such sysroot directory on Mac, your Postgres installation points to a path that no longer exists.

pg_config --cppflags

Reinstall Postgres to fix this.

Portability

By default, pgvector compiles with -march=native on some platforms for best performance. However, this can lead to Illegal instruction errors if trying to run the compiled extension on a different machine.

To compile for portability, use:

make OPTFLAGS=""

Installation Notes - Windows

Missing Header

If compilation fails with Cannot open include file: 'postgres.h': No such file or directory, make sure PGROOT is correct.

Mismatched Architecture

If compilation fails with error C2196: case value '4' already used, make sure you’re using the x64 Native Tools Command Prompt. Then run nmake /F Makefile.win clean and re-run the installation instructions.

Missing Symbol

If linking fails with unresolved external symbol float_to_shortest_decimal_bufn with Postgres 17.0-17.2, upgrade to Postgres 17.3+.

Permissions

If installation fails with Access is denied, re-run the installation instructions as an administrator.

Additional Installation Methods

Docker

Get the Docker image with:

docker pull pgvector/pgvector:pg18-trixie

This adds pgvector to the Postgres image (replace 18 with your Postgres server version, and run it the same way).

Supported tags are:

  • pg18-trixie, 0.8.2-pg18-trixie
  • pg18-bookworm, 0.8.2-pg18-bookworm, pg18, 0.8.2-pg18
  • pg17-trixie, 0.8.2-pg17-trixie
  • pg17-bookworm, 0.8.2-pg17-bookworm, pg17, 0.8.2-pg17
  • pg16-trixie, 0.8.2-pg16-trixie
  • pg16-bookworm, 0.8.2-pg16-bookworm, pg16, 0.8.2-pg16
  • pg15-trixie, 0.8.2-pg15-trixie
  • pg15-bookworm, 0.8.2-pg15-bookworm, pg15, 0.8.2-pg15
  • pg14-trixie, 0.8.2-pg14-trixie
  • pg14-bookworm, 0.8.2-pg14-bookworm, pg14, 0.8.2-pg14
  • pg13-trixie, 0.8.2-pg13-trixie
  • pg13-bookworm, 0.8.2-pg13-bookworm, pg13, 0.8.2-pg13

You can also build the image manually:

git clone --branch v0.8.2 https://github.com/pgvector/pgvector.git
cd pgvector
docker build --pull --build-arg PG_MAJOR=18 -t myuser/pgvector .

If you increase maintenance_work_mem, make sure --shm-size is at least that size to avoid an error with parallel HNSW index builds.

docker run --shm-size=1g ...

Homebrew

With Homebrew Postgres, you can use:

brew install pgvector

Note: This only adds it to the postgresql@18 and postgresql@17 formulas

PGXN

Install from the PostgreSQL Extension Network with:

pgxn install vector

APT

Debian and Ubuntu packages are available from the PostgreSQL APT Repository. Follow the setup instructions and run:

sudo apt install postgresql-18-pgvector

Note: Replace 18 with your Postgres server version

Yum

RPM packages are available from the PostgreSQL Yum Repository. Follow the setup instructions for your distribution and run:

sudo yum install pgvector_18
# or
sudo dnf install pgvector_18

Note: Replace 18 with your Postgres server version

pkg

Install the FreeBSD package with:

pkg install postgresql17-pgvector

or the port with:

cd /usr/ports/databases/pgvector
make install

APK

Install the Alpine package with:

apk add postgresql-pgvector

conda-forge

With Conda Postgres, install from conda-forge with:

conda install -c conda-forge pgvector

This method is community-maintained by @mmcauliffe

Postgres.app

Download the latest release with Postgres 15+.

Hosted Postgres

pgvector is available on these providers.

Upgrading

Install the latest version (use the same method as the original installation). Then in each database you want to upgrade, run:

ALTER EXTENSION vector UPDATE;

You can check the version in the current database with:

SELECT extversion FROM pg_extension WHERE extname = 'vector';

Clone this wiki locally