1. Overview
When verifying PostgreSQL patches on MacOS, I couldn’t find a straightforward blog to follow for setting up the environment quickly. This blog aims to document the steps I took to set up a PostgreSQL development environment on MacOS (verified on Apple Silicon M2). I hope it will be helpful for others when facing a similar task.
2. Installing Homebrew
To build PostgreSQL, certain tools and libraries need to be installed. If these are not managed by the default MacOS installation, a third-party package manager like Homebrew can be used. This blog will guide you through the steps of installing Homebrew and the necessary tools and libraries required to compile PostgreSQL and run make check-world
tests.
To install Homebrew, open a terminal and execute the following command:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
Follow the on-screen instructions to complete the installation. Once installed, add Homebrew to your PATH by running the provided commands in the terminal.
Additionally, you need to install Apple’s command line developer tools by running xcode-select --install
. This will open a GUI dialog window to complete the installation.
3. Installing Tools and Libraries with Homebrew
To install the necessary tools and libraries using Homebrew, execute the following commands in the terminal:
% brew install git
If you encounter an error related to running under Rosetta 2 in ARM, use the arch -arm64
prefix with Homebrew commands. For example:
% arch -arm64 brew install git
Install the icu4c
library, otherwise you can use –without-icu during configure step.
% arch -arm64 brew install icu4c
To have icu4c
in your PATH, add the following lines to your ~/.zshrc
file:
export PATH="/opt/homebrew/opt/icu4c/bin:$PATH"
export PATH="/opt/homebrew/opt/icu4c/sbin:$PATH"
For compilers to find icu4c
, set the following environment variables:
export LDFLAGS="-L/opt/homebrew/opt/icu4c/lib"
export CPPFLAGS="-I/opt/homebrew/opt/icu4c/include"
Finally, install pkg-config
and update the PKG_CONFIG_PATH
:
% arch -arm64 brew install pkg-config
% export PKG_CONFIG_PATH="/opt/homebrew/opt/icu4c/lib/pkgconfig:$PKG_CONFIG_PATH"
4. Compiling PostgreSQL and Running Tests
Clone the PostgreSQL repository from github:
% git clone https://github.com/postgres/postgres.git
% cd postgres
Configure and compile PostgreSQL with default configuration settings:
% ./configure
% make -j
To run the the basic tests, use the following command:
% make check
If see an error with some information similar to dyld[69058]: Library not loaded:
during make check
testing, then you need to workaround this issue by installing PostgreSQL once either sudo make install
if you use default prefix during configure process or make install
if you specified the prefix pointing to your directory.
If your make check
passed all the test cases, then it is time to run additional tests, including TAP tests, consider enabling --enable-tap-tests
during the configure process. For example:
% ./configure --enable-tap-tests
% make -j
% make check-world
If you encounter errors due to missing Perl modules, you can install them from CPAN. Below is the example I used to install the missing perl modules on my MacOS:
% sudo perl -MCPAN -e 'install Bundle::CPAN'
% sudo perl -MCPAN -e 'install IPC::Run'
% sudo perl -MCPAN -e 'install Test::Harness'
% sudo perl -MCPAN -e 'install Test::Simple'
% sudo perl -MCPAN -e 'install Time::HiRes'
Alternatively, you can install perlbrew
locally and manage your Perl modules separately.
To install the latest Perl 5.36, execute the following commands:
% \curl -L https://install.perlbrew.pl | bash
% source ~/perl5/perlbrew/etc/bashrc
% perlbrew --notest install perl-5.36.1
Once perlbrew
and perl
are installed, update your shell’s configuration file to use the local Perl modules. For example, add the following lines to your ~/.bashrc
:
# Load perlbrew
source $HOME/perl5/perlbrew/etc/bashrc
# Set the desired Perl version
perlbrew switch perl-5.36.1
And include the following line in your ~/.zshrc
file if you want to persist the setup for all terminals.
source ~/.bashrc
When you want to switch back to the system Perl that comes with MacOS, remove the source ~/.bashrc
line from ~/.zshrc
or run perlbrew off
in a particular terminal to temporarily disable perlbrew
.
5. Summary
In this blog post, I shared the steps I followed to set up a PostgreSQL development environment on MacOS. By installing the necessary tools and libraries, compiling PostgreSQL, and running tests, you can verify patches and contribute to the PostgreSQL community. I hope this guide proves helpful to others facing similar challenges.

A software developer specialized in C/C++ programming with experience in hardware, firmware, software, database, network, and system architecture. Now, working in HighGo Software Inc, as a senior PostgreSQL architect.
Recent Comments