Install PostgreSQL on macOS and Windows

Installing PostgreSQL feels deceptively simple — you download an installer, click Next a few times, and assume everything is fine. But within an hour, you're staring at psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory on macOS or psql: error: could not connect to server: Connection refused on Windows, and your confidence evaporates. This lesson is your guided tour through installing PostgreSQL on macOS and Windows — not just clicking buttons, but understanding what each step does so you can diagnose and fix problems yourself. By the end, you'll have a running PostgreSQL server, a definite password you actually remember, and the knowledge to connect to it from a terminal — ready for the next lesson on creating your first database.

The problem this lesson solves

You need a local PostgreSQL server to practice SQL, build applications, or work through this tutorial track. The problem is that PostgreSQL installation is not one-size-fits-all: macOS and Windows have different native installers, different default paths, and different ways of starting the server. Without a clear, platform-aware guide, you'll waste hours on setup errors that have nothing to do with SQL itself. Worse, a misconfigured install can leave you with a server that starts silently in the background but refuses connections when you need it most — or a password you set once and immediately forgot, locking you out of your own database. This lesson removes those roadblocks by walking you through the official installers, explaining key options, and preempting the most common pitfalls.

Core concept / mental model

Think of PostgreSQL as a database engine that runs as a background service on your machine. Installing it involves three distinct layers:

1. Server software — the actual PostgreSQL database engine (the postgres process).
2. Client tools — programs like psql (the terminal-based SQL client) and pgAdmin (a graphical interface).
3. Service management — how your operating system starts and stops the server automatically (launchd on macOS, Windows Service on Windows).

The mental model is a restaurant kitchen: the database server is the kitchen where all the cooking (data processing) happens. The client tools are the waitstaff who take your orders (SQL queries) and bring back results. The service manager is the restaurant's opening and closing crew — it makes sure the kitchen is running when you need it, and shuts it down safely when you don't.

Key terms you'll encounter:

• Cluster — a collection of databases managed by a single server instance. The installer creates one for you with a default database called postgres.
• Port — PostgreSQL listens for connections on port 5432 by default. You'll need to remember this for connection strings.
• Superuser — the postgres user (or the user you create during install) has full control over the server. Treat it like a root account.

Pro tip: During installation, you'll be asked to set a password for the postgres superuser. Don't skip it — even on Windows where it's marked optional. You'll need this password to connect, and resetting it later is a hassle.

How it works step by step

The installation process is conceptually the same on both platforms, but the exact clicks differ. Here's the high-level flow:

1. Download the installer — Get the official installer from postgresql.org/download. For macOS, you'll typically download the EDB Installer (a .dmg or .pkg file). For Windows, you'll get the EDB Interactive Installer (a .exe file).
2. Run the installer — Launch the installer and follow the wizard. Key screens include: - Installation directory — Choose a path you can remember. Defaults are fine (e.g., C:\Program Files\PostgreSQL\16 on Windows, /Library/PostgreSQL/16 on macOS). - Data directory — Where your actual database files live. Default is inside the installation folder. Don't change this unless you have a reason. - Password — Set a strong password for the postgres superuser. Write it down somewhere safe. - Port — Keep 5432 unless you know it's already in use. - Locale — Use the default locale; changing it can cause encoding issues.
3. Complete the installer — On Windows, you'll be prompted to install Stack Builder (optional — skip it for now). The installer also sets up the service to start automatically. On macOS, the installer loads a launchd plist to auto-start the server.
4. Verify the installation — Open a terminal (Command Prompt or PowerShell on Windows) and run psql --version to confirm the client tools are installed. Then connect to the server with psql -U postgres and enter your password when prompted.
5. Add psql to your PATH (if needed) — On Windows, the installer does this automatically, but on macOS, the binaries are often not in your shell's PATH. You'll need to add them (see the hands-on section).

Behind the scenes, the installer runs the initdb command to create your cluster, starts the server, and configures it to run as a service. Your job is just to provide the right input at the right time.

Hands-on walkthrough

Let's get our hands dirty. Below are step-by-step guides for each platform.

macOS (EDB Installer)

1. Go to postgresql.org/download and click macOS. Choose the latest version (e.g., 16.x) and download the .dmg file.
2. Double-click the .dmg to mount it, then run the .pkg installer.
3. Follow the wizard. When you reach the Password screen, enter a strong password for the postgres user and remember it.
4. Accept the default port 5432 and locale.
5. After installation, add the PostgreSQL binaries to your PATH. Open Terminal and run:

# Replace 16 with your installed version
sudo mkdir -p /etc/paths.d && echo '/Library/PostgreSQL/16/bin' | sudo tee /etc/paths.d/postgresql

Alternatively, add this line to your ~/.zshrc (if you use zsh) or ~/.bash_profile:

export PATH="/Library/PostgreSQL/16/bin:$PATH"

Then reload your shell:

source ~/.zshrc

1. Verify the installation:

psql --version
psql -U postgres

Enter your password when prompted. You should see the postgres=# prompt.

Windows (EDB Interactive Installer)

1. Download the .exe installer from the same page.
2. Run the installer as Administrator (right-click → Run as administrator).
3. Click through the wizard. On the Password screen, set a password for postgres.
4. Accept the default port 5432.
5. When prompted about Stack Builder, uncheck it (you don't need it for this tutorial).
6. After installation, open Command Prompt or PowerShell and verify:

psql --version
psql -U postgres

The installer adds psql to your PATH automatically, so this should work from any directory. Enter your password to reach the postgres=# prompt.

Expected output (both platforms)

After running psql -U postgres, you should see something like:

psql (16.2)
Type "help" for help.

postgres=#

The postgres=# prompt means you're connected to the postgres database as the postgres user. Type \q to exit.

Compare options / when to choose what

While the EDB installer is the official recommended path, there are alternatives. Here's a comparison to help you decide:

When to choose what:

• Newcomers → EDB installer (this lesson's approach) for the least friction.
• macOS developers already using Homebrew → brew install postgresql@16 and brew services start postgresql@16 is clean and integrates with your tooling, but you'll manage the user and password manually (createuser -s postgres).
• Container-savvy teams → Docker gives you a disposable server; perfect for CI, but you must manage volumes and ports.
• Windows enterprise environments → EDB installer is still your best bet; the Windows service makes startup automatic and reliable.

Pro tip: If you install PostgreSQL via Homebrew, the default superuser is your macOS username (no password). You might need to create the postgres user manually with createuser -s postgres. The EDB installer avoids this confusion by creating postgres for you.

Troubleshooting & edge cases

Even with a successful install, you'll hit snags. Here are the most common issues and how to fix them.

psql: error: could not connect to server: Connection refused

Cause: The server isn't running, or it's listening on a different port.

Fix: - macOS: Start the server with pg_ctl -D /Library/PostgreSQL/16/data start (adjust version/path), or use the Postgres.app status menu icon if you used that. - Windows: Open Services (Win+R, type services.msc), find postgresql-x64-16, and click Start. Or run pg_ctl start from an admin prompt. - Check the port: psql -p 5433 if you chose a different port during install.

psql: error: connection to server on socket "/tmp/.s.PGSQL.5432" failed: No such file or directory (macOS)

Cause: The server isn't started; the socket file doesn't exist.

Fix: Same as above — start the server. If it's already running but the socket path is wrong, your client might be using a different PostgreSQL version's libraries (e.g., Homebrew vs. EDB). Check which psql to see which client you're using.

FATAL: password authentication failed for user "postgres"

Cause: Wrong password, or you never set one (e.g., Homebrew install with no password).

Fix: - Double-check the password you entered (case-sensitive). - On macOS Homebrew, use psql -U your_macos_username instead of postgres. - Reset the password by editing pg_hba.conf to trust temporarily (advanced), or re-run the installer to reset.

psql: error: could not connect to server: No such file or directory (Windows)

Cause: Similar to macOS — server not running, or client can't find the socket file (Windows uses TCP, not sockets, but the message is misleading).

Fix: Start the Windows service as above, and ensure you're using TCP: psql -h localhost -p 5432 -U postgres.

Port already in use

Cause: Another PostgreSQL instance (or a different app) is using port 5432.

Fix: Choose a different port during install (e.g., 5433), or stop the conflicting service. Check with lsof -i :5432 on macOS or netstat -ano | findstr :5432 on Windows.

Can't find psql in PATH (macOS)

Cause: The EDB installer doesn't always add binaries to PATH for the current shell.

Fix: Add the PATH export to your shell profile as shown earlier, or run psql with the full path: /Library/PostgreSQL/16/bin/psql.

What you learned & what's next

You've successfully installed PostgreSQL on macOS or Windows, verified it with psql --version, and connected to the server with the postgres superuser. You understand the mental model of server, client, and service management, and you know how to troubleshoot common connection issues. These skills are the bedrock for everything else in this track.

Next lesson: Create and manage your first database — where you'll learn CREATE DATABASE, \l to list databases, and how to create a dedicated user for your apps. With your server running, you can immediately try:

CREATE DATABASE practice;
\l

That's your first step toward practical PostgreSQL mastery. See you there!

Final pro tip: Bookmark this lesson for when you need to reinstall or help a colleague. The path from install to connection is the most fragile part of the journey — but now you have the guide.