PostgreSQL: extension is not available

What it means

CREATE EXTENSION postgis asks the server to load an extension, using files that must already be installed on the machine where PostgreSQL runs: a control file (postgis.control), SQL scripts, and usually a compiled library. The server looked in its extension folder and found no control file by that name:

ERROR:  extension "postgis" is not available
HINT:  The extension must first be installed on the system where PostgreSQL is running.

The wording depends on the version. PostgreSQL 15, 16 and 17 add the path they looked at:

ERROR:  extension "postgis" is not available
DETAIL:  Could not open extension control file "/usr/share/postgresql/15/extension/postgis.control": No such file or directory.
HINT:  The extension must first be installed on the system where PostgreSQL is running.

PostgreSQL 14 says only the second part, as the error itself (code 58P01):

ERROR:  could not open extension control file "/usr/share/postgresql/14/extension/postgis.control": No such file or directory

It’s about files on the server. Installing PostGIS or pgvector on your Mac doesn’t help a server running in Docker, in a VM or in the cloud, and a package built for one major version doesn’t serve another.

Common causes

The extension isn’t installed on the server. The core “contrib” extensions (pgcrypto, pg_trgm, uuid-ossp, hstore, citext…) ship with most builds, but PostGIS, pgvector (vector), TimescaleDB and the like are separate packages.
The wrong name. The extension is uuid-ossp (with a hyphen, so it needs double quotes in SQL), pgvector’s is vector, PostGIS’s is postgis.
Installed for another major version, for example postgresql-16-postgis-3 on a server running PostgreSQL 18.
A Docker image without it: the official postgres image has the contrib extensions but not PostGIS or pgvector.
A hosted service that doesn’t offer it, or offers it only after you enable it in its settings.

How to fix it

See what the server has

SELECT name, default_version, installed_version
FROM pg_available_extensions
ORDER BY name;

If the extension isn’t in this list, the server can’t find its files. If it is but installed_version is empty, it’s available but not yet created in this database: run CREATE EXTENSION.

Install the package on the server

Match the server’s major version (SHOW server_version;). On Debian or Ubuntu with the PostgreSQL project’s packages, the version is in the package name:

sudo apt install postgresql-18-postgis-3 postgresql-18-pgvector

For Docker, use an image that includes the extension, such as postgis/postgis or pgvector/pgvector, at the same major version as your data. With Homebrew, install the extension’s formula and check that it was built for the PostgreSQL version you run.

Then, in each database that needs it:

CREATE EXTENSION IF NOT EXISTS postgis;
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

No restart is needed for most extensions; those that must be preloaded (pg_stat_statements, TimescaleDB) also need shared_preload_libraries and a restart.

On a hosted service

Check its list of supported extensions and, where needed, enable the extension in its console or parameter settings first. You can only install what the provider offers.

Permission is a different error

If the files are there but your role may not create the extension, the error is permission denied to create extension "…", with a hint about the CREATE privilege on the database; see permission denied.

Reproduce it

On the test servers (official Debian-based images, no PostGIS or pgvector):

CREATE EXTENSION postgis;
CREATE EXTENSION vector;
CREATE EXTENSION uuid_ossp;

PostgreSQL 18.6 gave extension "postgis" is not available with the hint and no DETAIL, and the same for vector and uuid_ossp. PostgreSQL 15.19, 16.14 and 17.11 added the DETAIL shown above. PostgreSQL 14.24 gave could not open extension control file "/usr/share/postgresql/14/extension/postgis.control": No such file or directory. With \set VERBOSITY verbose, the codes were 0A000 (18 and 15) and 58P01 (14). On all three, pg_available_extensions listed pg_trgm, pgcrypto and uuid-ossp but not postgis or vector.

In a throwaway PostgreSQL 18.6 container, a role without CREATE on the database got:

ERROR:  permission denied to create extension "pg_trgm"
HINT:  Must have CREATE privilege on current database to create this extension.

In Inlet

Inlet lists each database’s extensions. When CREATE EXTENSION fails, Inlet shows the server’s error with PostgreSQL’s hint, and What this error means opens this page.

extension is not available