Last Updated :
15 Apr, 2025
When working with PostgreSQL databases in Python, the psycopg2 library is a popular choice for database interaction. However, while installing or using psycopg2, you might encounter the error:
«pg_config executable not found»
This error occurs when Python’s package installer (pip) tries to compile the psycopg2 package but can’t locate the pg_config executable, which is necessary to find PostgreSQL headers and libraries.
Why does this error occur?
Let’s understand some of the possible causes that could lead to this error. These are a few common scenarios where things might go wrong and trigger this issue.
- PostgreSQL is not installed on your system.
- pg_config is not in your system’s PATH.
- You’re trying to install psycopg2 (source version) and it requires compilation.
- You’re on Windows and PostgreSQL binaries are not configured properly.
- Missing development packages required for compilation (mostly on Linux).
Solutions for different operating system
Depending on your operating system, the steps to resolve the «pg_config executable not found» error can vary. Below are platform-specific solutions to help you fix it quickly.
Table of Content
- Solutions for different operating system
- For Windows
- For Linux
- For macOS
For Windows
Let’s follow these steps to solve the issue on a Windows system.
Step 1: Install PostgreSQL
- Download from the official site: https://www.postgresql.org/download/windows/
- During setup, ensure that the “Development Tools” option is selected.
Step 2: Add pg_config to PATH
- Locate pg_config.exe, usually here:
C:\Program Files\PostgreSQL\13\bin\pg_config.exe
- Add the bin folder to the system PATH:
setx PATH «%PATH%;C:\Program Files\PostgreSQL\13\bin»
Step 3: Install psycopg2
pip install psycopg2
Step 4: Alternative (Skip Compilation)
pip install psycopg2-binary
This version includes precompiled binaries and doesn’t need pg_config.
For Linux
Let’s follow these steps to fix the “pg_config executable not found” error on a Linux system.
Step 1: Install PostgreSQL and Development Headers
sudo apt update
sudo apt install postgresql postgresql-contrib libpq-dev python3-dev
Step 2: Install psycopg2
pip install psycopg2
Step 3: Alternative (No Compilation Needed)
pip install psycopg2-binary
For macOS
Here’s how to resolve the issue on macOS, especially for users using Homebrew.
Step 1: Install PostgreSQL using Homebrew
brew install postgresql
Step 2: Check pg_config Path
which pg_config
Example output:
/opt/homebrew/bin/pg_config
Step 3: Add pg_config to PATH (if not already there)
- Add the following to your shell profile (e.g., ~/.zshrc or ~/.bash_profile):
export PATH=»/opt/homebrew/opt/postgresql/bin:$PATH»
- Then reload:
source ~/.zshrc # or source ~/.bash_profile
Step 4: Install psycopg2
pip install psycopg2
Step 5: Alternative (Skip Compilation)
pip install psycopg2-binary
Пройдите тест, узнайте какой профессии подходите
В процессе установки psycopg2 — популярного адаптера PostgreSQL для Python — может возникнуть некоторое количество проблем. Одной из самых распространенных
В процессе установки psycopg2 — популярного адаптера PostgreSQL для Python — может возникнуть некоторое количество проблем. Одной из самых распространенных является ошибка pg_config executable not found.
Вот типичный пример ситуации: при попытке установить psycopg2 через pip (pip install psycopg2) в терминале выводится сообщение об ошибке:
Error: pg_config executable not found.
Please add the directory containing pg_config to the PATH
or specify the full executable path with the option:
python setup.py build_ext --pg-config /path/to/pg_config build ...
or with the pg_config option in 'setup.cfg'.
Command python setup.py egg_info failed with error code 1
Это означает, что система не может найти исполняемый файл pg_config, который необходим для установки psycopg2.
В большинстве случаев проблема решается добавлением пути к исполняемому файлу pg_config в переменную окружения PATH. Если команда which pg_config возвращает путь к исполняемому файлу, то он должен быть добавлен в PATH. Это можно сделать с помощью следующей команды в терминале:
export PATH=$PATH:/path/to/pg_config
Тем не менее, бывают случаи, когда даже после добавления пути к pg_config в PATH ошибка не исчезает. В этом случае можно попробовать указать полный путь к pg_config во время установки psycopg2:
python setup.py build_ext --pg-config /path/to/pg_config build ...
Если и это не помогает, нужно проверить, действительно ли в указанной директории находится исполняемый файл pg_config. Если он там есть, то возможно, проблема в правах доступа. В таком случае помочь может запуск команд с правами суперпользователя (sudo).
Важно учесть, что в разных операционных системах могут быть свои нюансы при установке psycopg2 и работе с переменными окружения. Например, на RHEL 5.5 могут потребоваться дополнительные действия.
В любом случае, не стоит отчаиваться при возникновении проблем — Python обладает большим и активным сообществом, где всегда можно найти помощь.
Debugging Guides
• 1 min read
Whenever you’re trying to install the package Psycopg2, the PostgreSQL database adapter created for the Python language, you might run into a familiar error:
Error: pg_config executable not found.
Please add the directory containing pg_config to the PATHLuckily, this is a pretty easy to fix error and below we will explain how to solve the «pg_config executable not found» error on Windows, Mac and Linux. Let’s dig it!
Understanding the «pg_config executable not found» error
You will run into this error message when a Python package installation needs the PostgreSQL development libraries and headers. The components are essential for compiling and linking the required files during the installation process.
To solve the «pg_config executable not found» error, here’s what you need to do for each platform.
Windows users:
- Get the latest PostgreSQL installation from the official website: https://www.postgresql.org/download/windows/
- Download the relevant installer, either x86 or x64
- Run the installer and select the relevant development components
MacOS users:
- For MacOS, you can use either Homebrew or MacPorts as package managers
- Using Homebrew, open Terminal and run the following command:
brew install postgresqlTerminal
- Using MacPorts, open Terminal and run the following command:
sudo port install postgresql
Terminal
Linux users:
- On Ubuntu or Debian, open the Terminal and run the command:
sudo apt-get install libpq-devTerminal
Once you have installed the required PostgreSQL dev libraries and headers, you can proceed with reinstalling the Python package that caused the initial issue. This time, the installation should successfully locate the required «pg_config» executable and complete it fully.
Dealing with bugs is 💩, but not with Jam.
Capture bugs fast, in a format that thousands of developers love.
When using pip to install the pyscopg2 package, you might encounter the following error:
Error: pg_config executable not found.
pg_config is required to build psycopg2 from source.
Please add the directory containing pg_config to the $PATH
or specify the full executable path with the option:
python setup.py build_ext --pg-config /path/to/pg_config build ...
or with the pg_config option in 'setup.cfg'.
If you prefer to avoid building psycopg2 from source, please install
the PyPI 'psycopg2-binary' package instead.
This error occurs because the path to pg_config is not found in your system.
The pg_config executable file can be obtained by installing PostgreSQL in your system.
To resolve this error, you need to install PostgreSQL, which contains the pg_config executable file.
Use one of the following commands for Mac or Linux:
# For Mac
brew install postgresql
# For Linux
# Create the file repository configuration:
sudo sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'
# Import the repository signing key:
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
# Update the package lists:
sudo apt-get update
# Install the latest version of PostgreSQL.
# If you want a specific version, use 'postgresql-12' or similar instead of 'postgresql':
sudo apt-get -y install postgresql
For Windows, you can download the installer from the PostgreSQL download page and run the installer.
Once finished, you need to add the path to Postgres bin/ folder on the environment variable as shown below:
Now you should be able to install psycopg2 without receiving the error.
If installing PostgreSQL doesn’t work, then you can try to use the psycopg2-binary package instead of psycopg2.
pip install psycopg2-binary
# For pip3:
pip3 install psycopg2-binary
# if you don't have pip in your PATH:
python -m pip install psycopg2-binary
python3 -m pip install psycopg2-binary
# Windows
py -m pip install psycopg2-binary
# Anaconda
conda install psycopg2-binary
# Jupyter Notebook
!pip install psycopg2-binary
The psycopg2-binary is a pre-compiled psycopg2 distribution, which isn’t recommended for production use.
This is because the C libraries used to compile the package can’t be upgraded, requiring you to wait until the package maintainer released a newer version.
You need to build psycopg2 from source if you want to maintain the ability to upgrade the package binary yourself.
I hope this tutorial is helpful. See you in other tutorials! 👋
- Author
- Recent Posts
I started writing code around 20 years ago, and throughout the years, I have gained a lot of expertise from hands-on experience as well as learning from others. This website has also grown with me and is now something that I am proud of.
Error: pg_config executable not found can show up while installing psycopg2 if you have any missing packages or the directory containing pg_config is not added to the PATH. The commands working as solutions for the given error depend on the core issue and the type of your operating system.
Thus, this post contains all the important commands from which you can choose the appropriate one as per your need. Continue reading to see what’s missing and how you can fill the void to eliminate the error.
JUMP TO TOPIC
- Why Is the Error: pg_config Executable Not Found Occurring?
- – The Directory Containing pg_config Isn’t Added To the PATH
- – Missing Packages or Dependencies
- – The pgxnclient Isn’t Meant To Work on Windows
- How To Fix the Error: pg_config Executable Not Found?
- – Check and Add the Directory To the Path
- – Go for psycopg2-binary
- – Choose a Linux System
- – Get a libpq-dev for Your Linux System
- – Gift Your macOS PC the PostgreSQL Package
- – Grab python-devel and postgresql-devel for CentOS and REHL
- Conclusion
The given error is occurring because of the absence of the directory containing the pg_config file in the PATH. Other prominent reasons that could lead to this error include missing dependencies or packages, and the inability of the pgxnclient to work on Windows.
The following sections discuss the causes to help you gain more clarity.
– The Directory Containing pg_config Isn’t Added To the PATH
It isn’t enough to install PostgreSQL and its required dependencies. If the directory that contains pg_config isn’t added to the PATH, the error: pg_config executable not found Docker will appear on your screen.
– Missing Packages or Dependencies
The missing packages or dependencies can result in the same error. Plus, you should never forget that each operating system’s required packages are different.
– The pgxnclient Isn’t Meant To Work on Windows
You might get the error: pg_config executable not found Windows 10 because the pgxnclient tool doesn’t work on Windows. It is a command-line tool for Linux systems only. However, it might be possible that the Windows support gets added to pgxnclient in time later.
How To Fix the Error: pg_config Executable Not Found?
You can fix the mentioned error by adding the directory with pg_config to the PATH. Another uncommon but effective method involves opting for the psycopg2-binary library. Also, it would be helpful to install the missing packages based on your operating system’s needs.
Each of the solutions has been explained below for your assistance.
– Check and Add the Directory To the Path
Depending on the installation method, the directory that contains the pg_config binary file is often added to PATH by default. Therefore, it would be best to confirm if the missing directory is the main cause before trying to add it to eliminate the error. The following command will help you perform the confirmation:
Once you run it, it will return either the path of the said directory or an empty result. In case of getting an empty result, you should run the below command to add the directory to PATH:
export PATH=/usr/lib/postgresql/<version>/bin/:$PATH
Don’t forget to replace the “<version>” with the correct libpq version and the “:$PATH” with the required directory to fill the void in the PATH and kill the error.
Now, if you run pip install psycopg2, you won’t get the error: pg_config executable not found psycopg2-binary.
– Go for psycopg2-binary
An easier way to remove the error is to install psycopg2-binary instead of psycopg2. Although both of the given libraries provide you with the same code, the former is easier to install than the latter. Plus, there is a difference between the ways the given libraries install the code on your system.
Considering the installation of the libraries, the installation of the psycopg2 library demands many prerequisites. Plus, it will ask you to find some programs and files on your PC, which won’t be easy. On the other hand, the psycopg2-binary library doesn’t demand more than running an installation command.
So, here you go with the command that won’t show any errors and bless your PC with the required code:
pip install psycopg2-binary
However, remember that you can’t perform highly advanced tasks while using psychopg2-binary library.
– Choose a Linux System
If you want to run pgxnclient smoothly without encountering any errors, you should go for Linux systems. Your Linux PC will let you easily use pgxnclient to interact with the PostgreSQL Extension Network and perform your tasks.
– Get a libpq-dev for Your Linux System
If the cause of the error is a missing package, installing the libpq-dev package on your Linux system would be helpful. Whether you are using Ubuntu, Alpine, Debian, or a Debian-based distribution, the libpq-dev library will do the work and remove the error. The given package is built following Debian’s libpq-dev package.
It comes with a minimal set of PostgreSQL binaries and headers required for building third-party applications for PostgreSQL. Here is how you can install the given package:
sudo apt-get install libpq-dev
You can also install the python-dev package for extra benefits. The package contains the header files developers need to build Python extensions. The below command will allow you to install the libpq-dev and python-dev libraries together:
sudo apt-get install libpq-dev python-dev
The given command is sufficient to eliminate all the chances for the error: pg_config executable not found. Alpine.
However, if python-dev doesn’t seem to work for you, replace it with python3-dev.
– Gift Your macOS PC the PostgreSQL Package
Receiving the error: pg_config executable not found mac is often related to the absence of the PostgreSQL package. Therefore, you should install it immediately to make the error disappear from your screen. The recommended way to install PostgreSQL on macOS is by using the Homebrew software. In case you have heard about Homebrew for the first time, here is its short introduction:
It is a free package manager for macOS that makes it easier for you to install, update, or delete software by running commands in the terminal. Thus, you can use it to install the latest versions of different developer tools for macOS, such as Python, PHP, PostgreSQL, etc.
Please implement the following instructions to install Homebrew:
- Select Go in the Finder.
- Hit Utilities to view all the utilities.
- Find and open the Terminal application.
- Execute the command: xcode-select –install to install the XCode command line tools.
- Hit Install when asked if you would like to proceed with the installation.
- Click Agree if you agree to the Xcode License Agreement.
- Wait for some time until the installation is complete.
- If you are using macOS High Sierra, Sierra, El Capitan, or earlier, execute: /usr/bin/ruby -e “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install).”
- But if you are using Catalina, Mojave, or Big Sur, execute the following: /bin/bash -c “$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh).”
- Upon asking, provide your administrator password.
- Hit Return to continue.
- Let the downloading process be completed.
- Click Return to install Homebrew.
- Wait until you see the “Installation successful” message on your screen.
Now, you can run the command attached below to install PostgreSQL using Homebrew and kick away the error.
– Grab python-devel and postgresql-devel for CentOS and REHL
While using CentOS and REHL operating systems, the best way to eliminate the error is to install the python-devel and postgresql-devel packages. The python-devel package has the same contents as the python-dev package. Hence, you can call it the python-dev package for CentOS and REHL.
Next, the postgresql-devel package contains the libraries and header files required to compile C and C++ applications. These applications will interact with a PostgreSQL Data Management System. Along with this, you’ll see the package offering you with ecpg Embedded C Postgres preprocessor.
So, you can run the command shared below to get both of the stated packages and resolve the error pg_config executable not found. CentOS 7.
sudo yum install postgresql python-devel postgresql-devel
Conclusion
The above post informed you about various packages that you can install on your PC to eliminate the error. Also, it made it easier for you to modify the PATH and bless it with the needed directory. Here you go with some more noteworthy points from the article:
- Installing the psycopg2-binary library instead of psycopg2 can help remove the error.
- Installing the libpq-dev and python-dev packages on your Linux system can help you get rid of the error.
- On macOS, you should install the postgresql package by using the Homebrew package manager to kick away the error.
- The installation of postgresql-devel and python-devel on CentOS and REHL won’t disappoint you while removing the error.
- It would be of great help to note that the pgxnclient doesn’t work on Windows.
Now, you have understood that you don’t need to figure out how to install pg_config but only install a package or two to resolve the error.