Install PostgreSQL on macOS

This guide covers installing PostgreSQL on macOS using Homebrew, the recommended method for developers.

Prerequisites

macOS operating system
Homebrew installed (if not installed, run: /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)")

Installation Steps

1. Update Homebrew

First, ensure Homebrew is up to date:


                brew update

2. Install PostgreSQL

Install the latest version of PostgreSQL:


                brew install postgresql@15

Note:

Replace @15 with your desired version (e.g., @14, @16). Check available versions with brew search postgresql.

3. Start PostgreSQL Service

Start PostgreSQL as a background service:


                brew services start postgresql@15

What this does:

Starts PostgreSQL as a background service
Automatically starts PostgreSQL on system boot
Runs continuously until stopped

4. Verify Installation

Check if PostgreSQL is running:


                brew services list | grep postgresql

You should see postgresql@15 with status started.

5. Check PostgreSQL Version

Verify the installation:


                psql --version

6. Create Initial Database (if needed)

PostgreSQL creates a default database cluster during installation. If you need to create a new cluster:


                initdb /usr/local/var/postgresql@15

Note:

The default data directory location may vary. Check with brew info postgresql@15 for the exact path.

Alternative: Using Postgres.app

If you prefer a GUI application:

1. Download Postgres.app

Visit postgresapp.com and download the application.

2. Install and Launch

Drag Postgres.app to your Applications folder
Launch Postgres.app
Click “Initialize” to create a new server

3. Add to PATH (Optional)

To use psql from the command line, add Postgres.app to your PATH:


                # Add to ~/.zshrc or ~/.bash_profile
export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"

Then reload your shell:


                source ~/.zshrc
# or
source ~/.bash_profile

Post-Installation Setup

Set Up Command Line Tools

Add PostgreSQL binaries to your PATH (if not already added):


                # For Homebrew installation
echo 'export PATH="/opt/homebrew/opt/postgresql@15/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Connect to PostgreSQL

Test your connection:


                psql postgres

You should see the PostgreSQL prompt:


                postgres=#

Create Your First Database


                createdb my_database

Connect to Your Database


                psql my_database

Troubleshooting

PostgreSQL Service Won’t Start


                # Check logs
brew services info postgresql@15
 
# Try restarting
brew services restart postgresql@15

Port Already in Use

If port 5432 is already in use:


                # Find what's using the port
lsof -i :5432
 
# Stop the conflicting service or change PostgreSQL port

Permission Issues

If you encounter permission errors:


                # Fix ownership (adjust path as needed)
sudo chown -R $(whoami) /opt/homebrew/var/postgresql@15

Useful Commands

Stop PostgreSQL Service


                brew services stop postgresql@15

Restart PostgreSQL Service


                brew services restart postgresql@15

Check Service Status


                brew services list

View PostgreSQL Logs


                tail -f /opt/homebrew/var/log/postgresql@15.log

Next Steps

After installation, proceed to:

Setup Your First Database - Learn how to create databases and users
Common PostgreSQL Commands - Essential commands reference

On Linux instead? See Install PostgreSQL on Linux.