> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Install pg_pinecone

> Install the pg_pinecone extension on PostgreSQL 17 or 18 from a release archive, Postgres.app, PGXN, or Docker, or deploy it to a hosting platform.

Install pg\_pinecone with one of five methods, then enable the extensions in your database. The other pg\_pinecone guides assume you've done both.

## 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](#release-archive), [Postgres.app](#postgres-app), or [PGXN](#pgxn). To get Postgres and pg\_pinecone together, use [Docker](#docker) or a [hosting platform](#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](https://github.com/pgvector/pgvector#installation).

#### 2. Download the release archive

Download the release archive for your platform and Postgres version from the [releases page](https://github.com/pinecone-io/pg_pinecone/releases).

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](#pgxn), which builds from source, or [build from source](https://github.com/pinecone-io/pg_pinecone#readme) yourself.

#### 3. Copy the files into Postgres

Extract the archive and copy its files into your Postgres installation.

The commands use `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:

```bash Linux theme={null}
PG=17
tar xzf pg_pinecone-0.13.0-pg$PG-linux-x86_64.tar.gz
sudo cp usr/lib/postgresql/$PG/lib/pg_pinecone.so "$(pg_config --pkglibdir)/"
sudo cp usr/share/postgresql/$PG/extension/pg_pinecone* "$(pg_config --sharedir)/extension/"
```

```bash macOS theme={null}
PG=17
tar xzf pg_pinecone-0.13.0-pg$PG-darwin-arm64.tar.gz
cp opt/homebrew/lib/postgresql@$PG/pg_pinecone.dylib "$(pg_config --pkglibdir)/"
cp opt/homebrew/share/postgresql@$PG/extension/pg_pinecone* "$(pg_config --sharedir)/extension/"
```

On Linux arm64, use the `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](https://postgresapp.com/) 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](https://postgresapp.com/extensions/), 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](https://pgxn.org/dist/pg_pinecone/) 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](https://github.com/pgvector/pgvector#installation).

#### 2. Install the build dependencies

Install the build dependencies and the [PGXN client](https://pgxn.github.io/pgxnclient/). For PostgreSQL 18, change `17` to `18` in the Postgres package name:

```bash Debian or Ubuntu theme={null}
sudo apt install build-essential pkg-config libssl-dev postgresql-server-dev-17 pgxnclient
```

```bash RHEL theme={null}
sudo dnf install gcc make pkgconf-pkg-config openssl-devel postgresql17-devel pgxnclient
```

On Red Hat Enterprise Linux (RHEL), `postgresql17-devel` and `pgxnclient` come from the [PostgreSQL Yum repository](https://www.postgresql.org/download/linux/redhat/), 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](https://www.rust-lang.org/tools/install), then cargo-pgrx 0.19.2, the version pg\_pinecone builds with:

```bash theme={null}
cargo install cargo-pgrx --version 0.19.2 --locked
```

#### 4. Build and install pg\_pinecone

Run the build, which takes a few minutes:

```bash theme={null}
pgxn install pg_pinecone
```

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

The [`pineconeteam/pg_pinecone`](https://hub.docker.com/r/pineconeteam/pg_pinecone) image is the [`pgvector/pgvector`](https://hub.docker.com/r/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:

```bash theme={null}
docker pull pineconeteam/pg_pinecone:0.13.0-pg17
```

#### 2. Start a container

Start a container named `pg_pinecone`, the name the connect command later on this page uses:

```bash theme={null}
docker run -d --name pg_pinecone \
  -e POSTGRES_PASSWORD=secret \
  pineconeteam/pg_pinecone:0.13.0-pg17 \
  -c shared_preload_libraries=pg_pinecone
```

The `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.

| Platform | Deploy | Connect |
| - | - | - |
| Render | [pg\_pinecone template](https://render.com/deploy?repo=https://github.com/pinecone-io/pg_pinecone_render) | In the service's **Shell**, run `psql -U postgres -d pg_pinecone`. |
| Railway | [pg\_pinecone template](https://railway.com/deploy/pg-pinecone) | On your computer, run `psql "YOUR_DATABASE_PUBLIC_URL"` with the `DATABASE_PUBLIC_URL` value from the service's **Variables** tab. If you don't have `psql`, install the [PostgreSQL client](https://www.postgresql.org/download/). |

The template creates the extensions, so you can skip [step 2](#2-enable-the-extensions-in-your-database).

## 2. Enable the extensions in your database

### 1. Connect to your database

Connect as a superuser with `psql`:

```bash Linux theme={null}
sudo -u postgres psql
```

```bash macOS theme={null}
psql postgres
```

```bash Docker theme={null}
docker exec -it pg_pinecone psql -U postgres
```

On Linux, the `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](https://postgresapp.com/) show.

### 2. Create the extensions

Create pgvector first, because pg\_pinecone builds on its `vector` type and operators. Extensions are enabled per database, so run these in each database where you want to use pg\_pinecone:

```sql SQL theme={null}
CREATE EXTENSION vector;
CREATE EXTENSION pg_pinecone;
```

## Next steps

* [Follow the quickstart](https://docs.pinecone.io/guides/pg-pinecone/quickstart.md) to create a sample table and search it with a `native` index.
* [Switch from pgvector to native](https://docs.pinecone.io/guides/pg-pinecone/switch-from-pgvector.md) on an existing table.
* [Search a table with full-text search](https://docs.pinecone.io/guides/pg-pinecone/full-text-search.md).
* [Search a table with semantic search](https://docs.pinecone.io/guides/pg-pinecone/semantic-search.md).
