How to Install PostgreSQL: Complete Local Setup
Install PostgreSQL on Windows, macOS, or Linux, create a local database for your app, verify it, and handle the setup details that matter.
Install PostgreSQL for your operating system, start the local server, then run psql --version. Next, create a dedicated role and database for your app, and test the connection with one command. That is all you need for a reliable first local setup.
Before you start
- A Windows, macOS, or Linux computer that can install software.
- A terminal: PowerShell, Terminal, or your Linux shell.
- A safe local password for the database role you will create.
1. Install and start PostgreSQL
- 01
Download the installer
Open the official Windows download page and choose the EDB installer.
- 02
Install the server
Keep PostgreSQL Server and Command Line Tools selected. Set a password for the postgres administrator role and keep port 5432 unless it is already in use.
- 03
Open SQL Shell
Open SQL Shell (psql) from the Start menu, accept the suggested connection settings, then enter the password you chose.
Official Windows download
psql --version
# If this is not found, use SQL Shell or add PostgreSQL's bin folder to PATH.2. Create a database for your app
Inside psql, create a login role and a database it owns. Replace the example password with your own local password.
CREATE ROLE myapp LOGIN PASSWORD 'choose-a-local-password';
CREATE DATABASE myapp_development OWNER myapp;
\c myapp_development myapp
CREATE TABLE setup_check (message text NOT NULL);
INSERT INTO setup_check VALUES ('PostgreSQL is ready');
SELECT * FROM setup_check;3. Verify the connection
Exit psql with \q, then run this command in a fresh terminal. A successful result prints the role and database name.
psql 'postgresql://myapp:your-password@localhost:5432/myapp_development' -c 'SELECT current_user, current_database();'You are ready when
- psql --version prints a version.
- The connection test returns myapp and myapp_development.
- SELECT * FROM setup_check; returns one row.
Connect your application
Put the connection URL in your local environment file, not in source code. Most Node.js, Python, and other database libraries use this format.
# Keep this file out of Git
DATABASE_URL=postgresql://myapp:your-password@localhost:5432/myapp_developmentWork with your local database
You can use pgAdmin if you prefer a visual interface, but keep psql available. It is the quickest way to confirm exactly which server, role, and database your application is using.
\conninfo -- show the current connection
\l -- list databases
\du -- list roles
\dt -- list tables
SELECT version();
\q -- quit psqlOptional tools and reference
Troubleshoot common errors
| Problem | Try this |
|---|---|
| psql: command not found | Close and reopen the terminal. If it still fails, use SQL Shell on Windows or add PostgreSQL's bin folder to PATH. |
| connection refused | Start the PostgreSQL service, then try again with -h localhost -p 5432. |
| password authentication failed | Check that the URL uses myapp, then reset that role's password from an administrator connection. |
| role or database does not exist | Run \du to list roles and \l to list databases. Create the missing item or correct the URL. |
| port 5432 is already in use | Stop the other local database or configure one server to use another port and update the URL. |
Frequently asked questions
Do I need pgAdmin?
No. pgAdmin is optional. psql is enough to create a role, create a database, and confirm that your application can connect.
Which PostgreSQL version should I install?
Use a supported stable version unless your team or hosting provider requires a specific version.
Should my app use the postgres role?
No. Create a dedicated role for each application, as shown above. It keeps your application connection clear and avoids unnecessary administrator access.
Can I use Docker instead?
Yes, especially when a project already supplies a Docker Compose file. For a first setup, a native installation is often easier because you can focus on one server and one connection.
Can I change port 5432?
Yes. If another service already uses it, choose a different port and make the same change in your DATABASE_URL.
What if my password contains @ or :?
Those characters need URL encoding inside DATABASE_URL. For example, @ becomes %40. A simple local password avoids this extra step while you are learning.
How do I back up my local database?
Use pg_dump -U myapp -d myapp_development > backup.sql from a terminal. Keep the backup somewhere safe; restoring it replaces or adds data depending on the command you use.
How do I stop PostgreSQL?
Stop it through the tool that started it: Windows Services, brew services on macOS, or systemctl on Linux. Do not delete its data directory.