> ## Content Index
> Fetch the complete content index at: https://rolloutready.com/llms.txt
> Use this file to discover other available public pages before exploring further.

# How to Install PostgreSQL on Mac: A Clear Step-by-Step Guide
- URL: https://rolloutready.com/install-postgresql-mac/
- Published: 2026-10-24T03:29:00.000Z
- Updated: 2026-10-24T03:29:00.000Z
- Description: This guide explains how to install PostgreSQL on Mac using Homebrew, Docker, and Postgres.app with clear instructions and troubleshooting tips.
- Author: Daniel Hayes
- Tags: PostgreSQL, Mac, Database Installation, Homebrew, Docker

This guide explains how to install PostgreSQL on Mac using multiple popular methods, including Homebrew, Docker, and Postgres.app. It covers preparation steps, installation details, starting the server, client tools, and uninstallation procedures. Troubleshooting common issues is also included to ensure a smooth setup.

Mac users can choose the best installation method for their needs, whether it is a lightweight Homebrew setup or containerized with Docker. Each method comes with explicit commands and configuration tips, making the process straightforward. Clear instructions help avoid common pitfalls like conflicting versions or permission errors.

The guide assumes a macOS environment with administrator access and a basic familiarity with the Terminal app. It focuses on practical, actionable steps to get PostgreSQL running efficiently without unnecessary complexity or jargon.

## Before you start: What is needed to install PostgreSQL on Mac

PostgreSQL is a robust, open-source relational database system widely used for managing structured data. It supports recent macOS versions, typically from macOS 10.14 (Mojave) onward, ensuring compatibility with most modern Mac hardware. Before installation, confirm the macOS version to avoid compatibility issues.

For Homebrew installation, the system must have Homebrew installed and updated to the latest version. Homebrew streamlines package management on macOS, and an outdated or missing installation will block PostgreSQL setup.

Installing PostgreSQL via Docker requires Docker Desktop to be installed and running. Docker uses containerization, isolating PostgreSQL from the host system, which can consume more system resources but offers portability and environment consistency.

Choosing the right installation method depends on ease of use, system integration, and intended use. Homebrew offers tight macOS integration and is lightweight. Docker favors users needing isolated environments or multi-container setups. Consider the trade-offs in resource usage and management complexity before proceeding.

1. Check macOS version: Click Apple menu > About This Mac; verify version is 10.14 or later. Successful check ensures compatibility.
2. Verify Homebrew: Open Terminal and run *brew --version*. Seeing a version number means Homebrew is installed and ready.
3. Update Homebrew: Run *brew update*. Completion without error confirms Homebrew is current.
4. Check Docker Desktop: Open Docker from Applications. If Docker icon appears in the menu bar, it is running.

## How to install PostgreSQL on macOS using Homebrew

1. Check if Homebrew is installed by running `brew --version` in the terminal. If not installed, install it with `/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`. Successful installation outputs the Homebrew version.
2. Install PostgreSQL via Homebrew with `brew install postgresql`. The terminal will display progress and end with a success message.
3. Start the PostgreSQL service using `brew services start postgresql`. On success, the terminal shows *Service \`postgresql\` started successfully*.
4. Verify installation by checking the version with `psql --version`. Expected output is similar to `psql (PostgreSQL) 15.x`, confirming the installed version.
5. Set up the PATH environment variable if `psql` is not found. Add `export PATH="/usr/local/opt/postgresql/bin:$PATH"` to the shell profile (`.zshrc` or `.bash_profile`), then reload the profile.
6. Initialize the database if needed with `initdb /usr/local/var/postgres`. This creates the necessary database cluster for operation.

**Tip:** Use `brew services restart postgresql` to apply configuration changes without rebooting the Mac.

## How to install PostgreSQL on Mac using Docker

Docker offers an isolated environment for running PostgreSQL without affecting the host system. Start by installing Docker Desktop for Mac from the official Docker website, then launch it and ensure it is running properly.

1. Open the Mac terminal and pull the official PostgreSQL image: *docker pull postgres*. The terminal will download the latest PostgreSQL image from Docker Hub.
2. Run a new PostgreSQL container with port mapping and environment variables: *docker run --name pg-docker -e POSTGRES\_PASSWORD=your\_password -p 5432:5432 -d postgres*. This starts the container named *pg-docker* with the default PostgreSQL port mapped to the Mac and sets a password for the *postgres* user.
3. Verify the container is running by executing *docker ps*. The output should list the *pg-docker* container with status "Up".
4. Access PostgreSQL inside the container from the Mac terminal using: *docker exec -it pg-docker psql -U postgres*. This opens the PostgreSQL command line interface inside the container.

**Advantages:** Docker isolates PostgreSQL, avoiding version conflicts on the host. It simplifies cleanup and enables running multiple versions simultaneously. Resource use is slightly higher than native due to container overhead but remains efficient for most development tasks.

**Limitations:** Data storage requires volume mapping for persistence beyond container life. Network configuration can be more complex if connecting from other devices. Performance may lag behind native installs under heavy load.

## How to uninstall PostgreSQL on Mac

Uninstalling PostgreSQL cleanly depends on the installation method used. For Homebrew installations, start by stopping the service and uninstalling the package. Remove the PostgreSQL data directories and configuration files to free up disk space and prevent conflicts with future installations. Docker-based PostgreSQL requires stopping and removing containers and images. Verify removal by checking that no PostgreSQL-related processes or files remain, and clean up environment variables if set.

![How to uninstall PostgreSQL on Mac – how to install PostgreSQL on Mac](https://rolloutready.com/content/images/2026/10/install-postgresql-mac-2.webp)

1. Stop PostgreSQL if installed via Homebrew: `brew services stop postgresql`. Confirmation: terminal returns without error.
2. Uninstall PostgreSQL package: `brew uninstall postgresql`. Confirmation: Homebrew reports successful uninstallation.
3. Remove data and config directories, commonly located at `/usr/local/var/postgres` or `: rm -rf /usr/local/var/postgres. Confirmation: directories no longer exist.`
4. `If using Docker, list PostgreSQL containers with docker ps -a and stop them using docker stop [container_id]. Confirmation: container stops running.`
5. `Remove PostgreSQL Docker containers: docker rm [container_id]. Remove images: docker rmi postgres. Confirmation: containers and images are deleted.`
6. `Check and clean environment variables by examining files like ~/.bash_profile, ~/.zshrc, or ~/.bashrc for any PostgreSQL-related PATH entries and remove them. Confirmation: no PostgreSQL paths in environment variables after restarting the terminal.`
7. `Verify no PostgreSQL processes are running with ps aux | grep postgres. Confirmation: only the grep command itself appears.`

## `How to install PostgreSQL on Mac using the Postgres.app`

`Postgres.app offers a user-friendly, graphical way to install and manage PostgreSQL on Mac without relying on command-line package managers. It bundles PostgreSQL with a native macOS interface, making it suitable for developers who prefer a straightforward setup and easy server control.`

1. `Download Postgres.app from `[postgresapp.com](https://postgresapp.com/?ref=rolloutready.com)`` . The app is a single `.app` bundle, typically around 350 MB. ``
2. `Move Postgres.app to the Applications folder. Opening it for the first time registers PostgreSQL binaries and starts the server automatically.`
3. `Check the app’s icon in the menu bar, which indicates the server status. Clicking it reveals options to start, stop, or restart the PostgreSQL server.`
4. `` To use the `psql` client and other PostgreSQL tools in the terminal, add the Postgres.app binaries to the system PATH by running `echo 'export PATH="/Applications/Postgres.app/Contents/Versions/latest/bin:$PATH"' >> ~/.zshrc` for Zsh or the appropriate shell config. ``
5. `` Restart the terminal or run `source ~/.zshrc` to activate the PATH changes. Then, running `psql` opens the PostgreSQL interactive terminal connected to the default database. ``

`**When to choose Postgres.app:** It is ideal for users who want an all-in-one, GUI-based PostgreSQL experience without installing multiple dependencies. It is less suitable for production environments or automated setups but excellent for local development and testing.`

`The Postgres.app interface is minimal—primarily the menu bar icon with status indicators and preferences, emphasizing simplicity over extensive GUI management features.`

## `How to start the PostgreSQL server on Mac`

`Starting and managing the PostgreSQL server varies depending on the installation method. Each approach requires specific commands or actions to start, stop, and verify the server's status.`

### `Homebrew Installation`

1. `Open Terminal and run brew services start postgresql. This starts PostgreSQL as a background service.`
2. `To stop the server, run brew services stop postgresql.`
3. `Check the server status with brew services list. The output shows *started* next to postgresql if running.`

### `Postgres.app`

1. `Launch Postgres.app from the Applications folder.`
2. `Click the server icon in the menu bar; it should show a green indicator if the server is running.`
3. `To stop the server, select *Quit Server* from the menu bar icon.`

### `Docker Installation`

1. `Start the PostgreSQL container using docker start <container_name>.`
2. `Stop the container with docker stop <container_name>.`
3. `Verify the container is running by executing docker ps; the container should appear in the list.`

### `Verifying the Server`

1. `Check if PostgreSQL is listening on the default port 5432 by running lsof -i:5432. If output includes a postgres process, the server is active.`
2. `Alternatively, use pg_isready to test server readiness. A response like */tmp:5432 - accepting connections* confirms the server is running.`

## `How to install PostgreSQL client tools on Mac`

`The primary command-line client for PostgreSQL is *psql*. It can be installed via Homebrew by running brew install libpq. After installation, link the client tools with brew link --force libpq. This provides access to psql and related utilities without installing the full PostgreSQL server. Alternatively, Postgres.app includes psql and other client tools bundled, accessible through its integrated terminal.`

`For graphical user interfaces (GUIs), several popular options exist. `[pgAdmin](https://www.pgadmin.org/download/pgadmin-4-macos/?ref=rolloutready.com)` is a comprehensive, open-source PostgreSQL management tool suitable for complex database administration. `[TablePlus](https://tableplus.com/?ref=rolloutready.com)` offers a sleek, lightweight interface with native Mac performance and supports multiple database types. Both require downloading and installing the app, then configuring a connection to the local PostgreSQL server by specifying host (usually localhost), port (default 5432), username, and password.`

`Server installation packages include client tools but installing clients separately allows lightweight access without running a server. Server and client installations differ chiefly in resource usage and scope: server packages run the database engine, while client tools only connect and manage databases remotely or locally.`

## `How to install PostgreSQL on Mac terminal`

1. `Open Terminal and run brew install postgresql. Successful installation shows messages ending with “==> Summary” and no errors.`
2. `Initialize the database with initdb /usr/local/var/postgres. On success, the output confirms the data directory is initialized.`
3. `Start the PostgreSQL server using pg_ctl -D /usr/local/var/postgres start. The terminal will return “server started” without error.`
4. `Set environment variables by adding export PATH="/usr/local/opt/postgresql/bin:$PATH" to the shell profile file (e.g., ~/.zshrc or ~/.bash_profile). Reload the profile with source ~/.zshrc.`
5. `Connect to PostgreSQL using the client by running psql postgres. A prompt starting with postgres=# indicates a successful connection.`

`**Tip:** If psql: command not found appears, verify the PATH includes PostgreSQL’s bin directory and that the shell profile is reloaded.`

![How to install PostgreSQL on Mac terminal – how to install PostgreSQL on Mac](https://rolloutready.com/content/images/2026/10/install-postgresql-mac-3.webp)

`Common issues include permission errors on the data directory—use chmod 700 /usr/local/var/postgres to fix—and conflicts if another PostgreSQL version is installed; verify active versions with brew list postgresql and running which psql.`

## `Troubleshooting common PostgreSQL installation issues on Mac`

`PostgreSQL installation on Mac can encounter several common issues including port conflicts, permission errors, service failures, environment misconfigurations, and Docker connection problems. Identifying error messages early guides effective resolution.`

### `Resolving port conflicts`

`Error message: *"FATAL: could not bind IPv4 socket: Address already in use"* indicates port 5432 is occupied. To fix, identify the occupying process with lsof -i:5432. Stop or reconfigure that service. Alternatively, change PostgreSQL's port in postgresql.conf by setting port = 5433 and restart the server.`

### `Fixing permission errors`

`Errors like *"could not create lock file"* or *"permission denied"* occur when PostgreSQL lacks directory access. Use sudo chown -R $(whoami) /usr/local/var/postgres to set ownership. Confirm directory permissions allow read/write. Restart the service to verify.`

### `Service not starting or crashing`

`When the PostgreSQL service fails silently or crashes, check logs at /usr/local/var/postgres/server.log. Common causes include corrupted data or config errors. Running pg_ctl -D /usr/local/var/postgres start manually often reveals errors. Repair or restore configuration files as needed.`

### `PATH and environment variable issues`

`Commands like psql not found usually stem from missing PATH entries. Add PostgreSQL binaries to PATH by editing ~/.zshrc or ~/.bash_profile with export PATH="/usr/local/opt/postgresql/bin:$PATH". Reload shell configuration and verify with which psql.`

### `Docker container connection problems`

`Connection refused errors when using Docker often result from incorrect port mapping or container not running. Confirm running containers with docker ps. Ensure ports are exposed with -p 5432:5432 during container launch. Use docker logs [container_id] for detailed error info.`

1. `Check for port conflicts: run lsof -i:5432 and stop conflicting services or change PostgreSQL port in config.`
2. `Fix permission errors: run sudo chown -R $(whoami) /usr/local/var/postgres and verify directory permissions.`
3. `Diagnose service failures: inspect logs at /usr/local/var/postgres/server.log and start manually with pg_ctl -D /usr/local/var/postgres start.`
4. `Correct PATH issues: add PostgreSQL binary directory to shell PATH and reload shell profile.`
5. `Resolve Docker connection issues: verify container is running with docker ps and ports are correctly mapped.`

## `Frequently asked questions`

### `How to uninstall postgresql in mac?`

`Uninstalling PostgreSQL on Mac requires removing the installed files and directories. If installed via Homebrew, run *brew uninstall postgresql* and then delete leftover data directories, typically located at /usr/local/var/postgres. For installations via Postgres.app, simply drag the app to the Trash and remove the ~/Library/Application Support/Postgres folder. Also, check for and remove any related launch agents or services to prevent automatic restarts.`

### `How to install postgresql on windows?`

`Download the official PostgreSQL installer for Windows from the EnterpriseDB website. Run the installer and follow on-screen prompts to choose installation directory, components, and set the database superuser password. After installation, use the pgAdmin graphical tool or command line to manage the database server.`

### `How to install PostgreSQL on Windows?`

`The PostgreSQL installation on Windows involves downloading the installer from the PostgreSQL official site, running it, and selecting desired features such as server, pgAdmin, and command line tools. The setup wizard guides through setting a password for the default database user and configuring port settings. Once installed, PostgreSQL runs as a Windows service automatically.`

### `How to uninstall PostgreSQL in Mac?`

`To uninstall PostgreSQL on Mac, remove the binaries and data directories based on the installation method. For Homebrew, use *brew uninstall postgresql* and delete /usr/local/var/postgres. For Postgres.app, delete the app and related support folders. Stop any running PostgreSQL services before removal to avoid conflicts.`

### `What is the Postgres app for Mac?`

`The Postgres.app is a standalone macOS application that bundles PostgreSQL server and tools in a single package. It allows users to run a PostgreSQL server without complex installations or command line setup. The app supports multiple PostgreSQL versions and includes a simple interface for managing databases locally.`

## `What this guide does not cover`

`This guide does not cover advanced PostgreSQL configuration or tuning, which requires deeper database administration knowledge. Users requiring a production-grade PostgreSQL setup with replication, clustering, or high availability should consult dedicated DBA resources tailored to those environments. The Docker method isolates PostgreSQL effectively but may introduce performance overhead and networking complexity compared to native installations.`

`For most users, selecting between Homebrew, Docker, or Postgres.app depends on specific needs such as ease of setup, isolation, or integration with other tools. The single most useful next step is to verify the PostgreSQL server is running correctly by executing psql --version in the terminal and connecting to the default database. This confirms the installation and readiness to begin database operations immediately.`

**See also:** [How to Install MySQL on Mac: A Step-by-Step Guide](https://macfixly.com/install-mysql-mac/?ref=rolloutready.com) · [How to Create and Use a Timeline in Canva: Complete Implementation Guide](https://techbookshelf.com/p/?ref=rolloutready.com) · [Moving from Moodle to Canvas: A Practical Checklist for Educators](https://macfixly.com/moving-moodle-canvas-checklist/?ref=rolloutready.com)