Install the pgai extension from source

July 10, 2025 · View on GitHub

⚠️ Note:

For Windows users, we recommend using the pgai Docker image to run the pgai extension. These instructions have only been tested on macOS and Linux.

To install pgai from source on a PostgreSQL server:

  1. Install the prerequisite software system-wide

    • PostgreSQL: Version 16 or newer is required.

    • Python3: if running python3 --version in Terminal returns command not found, download and install the latest version of Python3.

    • Pip: if running pip --version in Terminal returns command not found, install it with one of the pip supported methods.

    • PL/Python: follow How to install Postgres 16 with plpython3u: Recipes for macOS, Ubuntu, Debian, CentOS, Docker.

      macOS: the standard PostgreSQL brew in Homebrew does not include the plpython3 extension. These instructions show how to install from an alternate tap.

      • Postgresql plugin for the asdf version manager: set the --with-python option when installing PostgreSQL:

        POSTGRES_EXTRA_CONFIGURE_OPTIONS=--with-python asdf install postgres 16.3

    • pgvector: follow the install instructions from the official repository. This extension is automatically added to your PostgreSQL database when you install the pgai extension.

  2. Clone the pgai repo at the latest tagged release:

    git clone https://github.com/timescale/pgai.git --branch extension-0.8.0
cd pgai

  3. Install the pgai PostgreSQL extension:

    sudo just ext install

    Note: The install requires write access to system-owned paths to create the following files:

    • pgai's Python dependencies (in /usr/local/lib/pgai)
    • pgai's extension files (ai.control and ai--*.sql) (in Postgres' extension directory, typically /usr/share/postgresql/<pg version>/extension, but configurable. Use pg_config --sharedir to determine this path) If you would prefer to not run the install command using sudo, it must be run as a user with write access to the above paths.

    We use just to run project commands. If you don't have just you can install the extension with:

    sudo projects/extension/build.py install

  4. Connect to your database with a postgres client like psql v16 or PopSQL.

    psql -d "postgres://<username>:<password>@<host>:<port>/<database-name>"

  5. Create the pgai extension:

    CREATE EXTENSION IF NOT EXISTS ai CASCADE;

    The CASCADE automatically installs pgvector and plpython3u extensions.