As a developer, encountering errors is part of the job. One of the most common errors that developers encounter when trying to install the psycopg2 library on MacOS is the “pg_config executable not found” error. This error can be frustrating and confusing, especially for those who are new to MacOS or PostgreSQL. In this article, I will explain what the error means, why pg_config is required to build psycopg2 from source, and provide common and alternative solutions to resolve the “pg_config executable not found” error.
Understanding the “pg_config executable not found” error
The “pg_config executable not found” error occurs when the psycopg2 library cannot locate the pg_config executable file. The pg_config file is a configuration script for PostgreSQL that provides information about installed PostgreSQL libraries and their location on the system. psycopg2 uses the pg_config script to build the library from source during installation. Without the pg_config file, psycopg2 cannot be installed.
Why is pg_config required to build psycopg2 from source?
To understand why pg_config is required to build psycopg2 from source, we first need to understand how psycopg2 is installed. Psycopg2 is a PostgreSQL adapter for the Python programming language. It allows Python programs to connect to a PostgreSQL database and perform various database operations. Psycopg2 can be installed using pip, the Python package manager, or by building the library from source.
When installing psycopg2 from source, the library needs to be compiled on the target system. During the compilation process, psycopg2 needs to locate the PostgreSQL libraries on the system. This is where the pg_config script comes in. The pg_config script provides information about the PostgreSQL libraries and their location, allowing psycopg2 to compile and build the library on the target system.
Common solutions for the “pg_config executable not found” error
Installing psycopg2-binary instead of psycopg2
One of the easiest solutions to the “pg_config executable not found” error is to install psycopg2-binary instead of psycopg2. Psycopg2-binary is a pre-compiled binary package of the psycopg2 library. It does not require the pg_config script or any compilation during installation. To install psycopg2-binary, simply run the following command:
pip install psycopg2-binary
Using Homebrew to install PostgreSQL
Another solution to the “pg_config executable not found” error is to use Homebrew to install PostgreSQL. Homebrew is a package manager for MacOS that allows easy installation of various software packages, including PostgreSQL. To install PostgreSQL using Homebrew, follow these steps:
- Open the Terminal app on your Mac.
- Install Homebrew by running the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
- Once Homebrew is installed, run the following command to install PostgreSQL:
brew install postgresql
- After PostgreSQL is installed, run the following command to add the PostgreSQL bin directory to your PATH environment variable:
echo 'export PATH="/usr/local/opt/postgresql@12/bin:$PATH"' >> ~/.bash_profile
- Restart your Terminal app to apply the changes to your PATH environment variable.
Adding pg_config to the PATH environment variable
If you have already installed PostgreSQL on your Mac, you can add the pg_config file to your PATH environment variable. Adding pg_config to your PATH allows psycopg2 to locate the file during installation. To add pg_config to your PATH, follow these steps:
- Open the Terminal app on your Mac.
- Run the following command to locate the pg_config file:
find /usr/local/Cellar/postgresql -name "pg_config"
- Copy the path of the pg_config file. The path should look something like this:
/usr/local/Cellar/postgresql/13.0/bin/pg_config
- Run the following command to open your .bash_profile file:
nano ~/.bash_profile
- Add the following line to the end of the file:
export PATH="/usr/local/Cellar/postgresql/13.0/bin:$PATH"
- Save the file by pressing “Control + X”, then “Y”, then “Enter”.
- Restart your Terminal app to apply the changes to your PATH environment variable.
Manually installing pg_config on MacOS
If none of the above solutions work, you can manually install pg_config on your Mac. To do this, follow these steps:
- Download the PostgreSQL source code from the PostgreSQL website.
- Extract the source code to a directory on your Mac.
- Open the Terminal app on your Mac.
- Navigate to the directory where the PostgreSQL source code is extracted.
- Run the following commands to configure and install PostgreSQL:
./configure
make
sudo make install
- After PostgreSQL is installed, run the following command to add the PostgreSQL bin directory to your PATH environment variable:
echo 'export PATH="/usr/local/pgsql/bin:$PATH"' >> ~/.bash_profile
- Restart your Terminal app to apply the changes to your PATH environment variable.
Troubleshooting tips for the “pg_config executable not found” error
If you are still encountering the “pg_config executable not found” error after trying the above solutions, here are some troubleshooting tips:
- Check that PostgreSQL is installed on your system and that the bin directory is added to your PATH environment variable.
- Check that the pg_config file exists in the bin directory of your PostgreSQL installation.
- Check that the pg_config file has the correct permissions. The file should be executable by the user running the installation.
- Try running the installation with sudo privileges. This may help if the installation is encountering permission issues.
Alternative PostgreSQL libraries to consider
If you are still unable to resolve the “pg_config executable not found” error, there are alternative PostgreSQL libraries that you can consider using. Here are a few options:
- PyGreSQL: A pure-Python PostgreSQL client library that does not require the pg_config file.
- SQLAlchemy: A Python SQL toolkit that supports multiple SQL databases, including PostgreSQL.
- Psycopg: A PostgreSQL adapter for the Python programming language, similar to psycopg2.
Conclusion
Encountering errors is a normal part of the development process, but it can be frustrating when you are unable to resolve them. The “pg_config executable not found” error is a common error that developers encounter when trying to install psycopg2 on MacOS. In this article, we discussed what the error means, why pg_config is required to build psycopg2 from source, and provided common and alternative solutions to resolve the error. By following these solutions and troubleshooting tips, you should be able to successfully install psycopg2 on your MacOS system and continue with your development work.
