Prerequisites
- A PostgreSQL 17 or 18 server with a superuser role, Docker, or an account on a supported hosting platform. Postgres.app, the Docker image, and the hosting platform templates include Postgres and pgvector.
1. Install pg_pinecone
Choose one method. On a server you manage, use a release archive, Postgres.app, or PGXN. To get Postgres and pg_pinecone together, use Docker or a hosting platform template.Release archive
1
Install pgvector
If your server doesn’t have pgvector, install it. Run
sudo apt install postgresql-17-pgvector (or postgresql-18-pgvector) on Debian or Ubuntu, brew install pgvector on macOS, or see the pgvector installation guide.2
Download the release archive
Download the release archive for your platform and Postgres version from the releases page.Archives are published for PostgreSQL 17 and 18 on Linux x86_64, Linux arm64, and macOS arm64. The Linux x86_64 build needs a CPU that supports x86-64-v3 (Intel Haswell or newer, which covers current cloud instances), and the Linux builds need glibc 2.39 or later, such as Ubuntu 24.04 or Debian 13. On other platforms, including Debian 12, Ubuntu 22.04, RHEL 9, and older x86_64 CPUs, use PGXN, which builds from source, or build from source yourself.
3
Copy the files into Postgres
Extract the archive and copy its files into your Postgres installation.The commands use On Linux arm64, use the
PG=17. If your server runs PostgreSQL 18, change it to PG=18. To check your version, run pg_config --version. pg_config also reports where your Postgres installation keeps extension files:linux-arm64 archive. If more than one Postgres version is installed, use the pg_config that belongs to the server you’re installing into.Postgres.app
Postgres.app is a Mac app that runs PostgreSQL and includes pgvector. pg_pinecone is one of its downloadable extensions, built for PostgreSQL 18 on Apple silicon.1
Start a PostgreSQL 18 server
Open Postgres.app and start a PostgreSQL 18 server. If the server is new, click Initialize.
2
Install the extension
On the Postgres.app extensions page, find pg_pinecone and download it. Open the installer it downloads and follow the prompts.
3
Restart the server
Back in the Postgres.app window, click Stop, then Start, so the server can find the extension you installed.
PGXN
pgxn install downloads the pg_pinecone release on PGXN and builds it from source for your Postgres server.
1
Install pgvector
If your server doesn’t have pgvector, install it. Run
sudo apt install postgresql-17-pgvector (or postgresql-18-pgvector) on Debian or Ubuntu, brew install pgvector on macOS, or see the pgvector installation guide.2
Install the build dependencies
Install the build dependencies and the PGXN client. For PostgreSQL 18, change On Red Hat Enterprise Linux (RHEL),
17 to 18 in the Postgres package name:postgresql17-devel and pgxnclient come from the PostgreSQL Yum repository, and postgresql17-devel needs the CodeReady Builder (CRB) repository enabled. On macOS, you need only the Xcode Command Line Tools (xcode-select --install) and the PGXN client (brew install pgxnclient). On other platforms, install the equivalent packages.3
Install Rust and cargo-pgrx
Install Rust, then cargo-pgrx 0.19.2, the version pg_pinecone builds with:
4
Build and install pg_pinecone
Run the build, which takes a few minutes:The build targets the Postgres that the first
pg_config on your PATH belongs to. If more than one Postgres version is installed, put the pg_config of the server you’re installing into first on your PATH. On RHEL, pg_config isn’t on your PATH by default, so run export PATH=/usr/pgsql-17/bin:$PATH first.Docker
Thepineconeteam/pg_pinecone image is the pgvector/pgvector image with pg_pinecone added, so it includes Postgres and pgvector. It runs on x86_64 and arm64 hosts. On x86_64, it needs a CPU that supports x86-64-v3, like the Linux x86_64 release archive.
1
Pull the image
The image includes its own Postgres, so you don’t need to match a server you already have. This command uses PostgreSQL 17, the more widely used of the two supported versions. For PostgreSQL 18, use the
0.13.0-pg18 tag here and in the next step instead:2
Start a container
Start a container named The
pg_pinecone, the name the connect command later on this page uses:shared_preload_libraries setting preloads pg_pinecone, which the remote engine, full-text search, and semantic search need. Setting it now saves a restart later.Hosting platform
Deploy a template to a hosting platform, then connect to it. Each template runs PostgreSQL 18 with pg_pinecone installed and preloaded.
The template creates the extensions, so you can skip step 2.
2. Enable the extensions in your database
Connect to your database
Connect as a superuser with On Linux, the
psql:postgres system user is the superuser that the package creates. With Homebrew or Postgres.app on macOS, your own user is the superuser. In the Docker image, the superuser is postgres. To connect to a different database or a remote server, add -d your_database, -h your_host, and -U your_superuser.With Postgres.app, if your terminal can’t find psql, add Postgres.app’s command-line tools to your PATH, as its installation steps show.Next steps
- Follow the quickstart to create a sample table and search it with a
nativeindex. - Switch from pgvector to native on an existing table.
- Search a table with full-text search.
- Search a table with semantic search.