Database

How to Access PostgreSQL in Ubuntu WSL with pgAdmin 4

If you have PostgreSQL running in WSL Ubuntu and want a GUI to manage it, pgAdmin 4 is the standard tool for the job.…

How to Access PostgreSQL in Ubuntu WSL with pgAdmin 4
Share:

How to Access PostgreSQL in Ubuntu WSL with pgAdmin 4

5 min read
2.4K views

If you have PostgreSQL running in WSL Ubuntu and want a GUI to manage it, pgAdmin 4 is the standard tool for the job. Start with localhost as the host in pgAdmin. WSL normally forwards Windows localhost connections to Linux, including in NAT mode with the default localhostForwarding setting.

This guide walks you through connecting pgAdmin 4 on Windows to a PostgreSQL instance in WSL Ubuntu.

Advertisement

Prerequisites

Step 1: Install pgAdmin 4 on Windows

Download pgAdmin 4 from the official site: pgadmin.org/download. Install it on Windows, not inside WSL. pgAdmin is a desktop app. it runs on the Windows side and connects to PostgreSQL over the network.

Run through the installer with the defaults. Once installed, open pgAdmin from the Start menu. Current pgAdmin desktop versions use the operating system password store by default. A master password may be needed if that store is unavailable. Your PostgreSQL role password is configured separately.

Step 2: Check PostgreSQL Configuration

Try the connection in Step 4 using localhost first. Keep PostgreSQL listening on localhost for that path. Only apply the external-listener and host access changes below if you need the direct WSL IP fallback.

Advertisement

Edit postgresql.conf

Find your PostgreSQL config file. Run pg_lsclusters and use the installed version and cluster name. For a version 16 cluster named main, the example path is:

sudo nano /etc/postgresql/16/main/postgresql.conf

If you installed a different version, replace 16 with your version number (check with pg_lsclusters).

Find the line that says listen_addresses (it’s usually commented out near the top) and change it to:

listen_addresses = '*'

Make sure you remove the # at the beginning of the line if it’s commented out. The * means PostgreSQL will accept connections on all network interfaces, not just localhost.

Edit pg_hba.conf

This file controls who is allowed to connect and how they authenticate. Open it:

sudo nano /etc/postgresql/16/main/pg_hba.conf

Add this line at the end of the file for the direct-IP fallback. Replace WINDOWS_HOST_IP/32 with the actual Windows client address reported by PostgreSQL. An existing matching rule earlier in the file takes precedence:

# Allow connections from Windows host (pgAdmin)
host    all    all    WINDOWS_HOST_IP/32    scram-sha-256

Here’s what each column means:

  • host. TCP/IP connection (not local socket)
  • all. any database
  • all. any user
  • WINDOWS_HOST_IP/32. the single Windows client address
  • scram-sha-256. require password authentication

For localhost, check the existing 127.0.0.1/32 and ::1/128 host rules and use SCRAM password authentication. For a direct IP connection, keep access restricted to your Windows source address and firewall rules.

Restart PostgreSQL

sudo service postgresql restart

Verify it’s running:

sudo service postgresql status

Step 3: Choose localhost or the Direct IP Fallback

Use localhost in pgAdmin first. If forwarding is unavailable or fails after checking port conflicts and WSL settings, get the WSL address for a direct connection:

hostname -I

This returns something like 172.20.x.x. Copy that IP. you’ll need it in the next step.

Heads up: The WSL IP address changes every time you restart WSL or reboot your Windows machine. So if pgAdmin can’t connect after a restart, run hostname -I again and update the server connection in pgAdmin.

Optional: Mirrored Networking

If you’re on a recent Windows 11 build, you can enable mirrored networking mode in WSL2 so that localhost from Windows reaches WSL directly. Add this to your %USERPROFILE%\.wslconfig file on the Windows side:

[wsl2]
networkingMode=mirrored

Save your work, then restart WSL with wsl --shutdown from PowerShell. After this, you can use localhost instead of the WSL IP in pgAdmin, and the IP won’t change on restarts. This feature requires Windows 11 22H2 or later.

Step 4: Connect pgAdmin to PostgreSQL

Open pgAdmin on Windows and register a new server:

  1. Right-click Servers in the left panel and select Register > Server
  2. In the General tab, give it a name (anything you want, like “WSL PostgreSQL”)
  3. Switch to the Connection tab and fill in:
    • Host name/address: localhost first, or your WSL IP for the direct connection fallback
    • Port: 5432
    • Maintenance database: postgres
    • Username: your PostgreSQL user (e.g., postgres or the user you created)
    • Password: your PostgreSQL password
  4. Check Save password if you don’t want to type it every time
  5. Click Save

If everything is configured correctly, pgAdmin will connect and you’ll see your databases in the left panel.

pgAdmin 4 connected to PostgreSQL running in WSL Ubuntu

Troubleshooting

Connection refused

Most common cause: PostgreSQL isn’t running. Make sure your WSL terminal is open and run:

sudo service postgresql start

If systemd is enabled in WSL, run sudo systemctl enable --now postgresql to start PostgreSQL and enable it when the distribution starts. Closing one terminal does not itself stop PostgreSQL. If WSL shuts down, start the distribution again before connecting.

Connection timed out

The IP address probably changed. Run hostname -I in WSL and update the host in pgAdmin’s server connection settings (right-click the server > Properties > Connection).

Password authentication failed

If you never set a password for the postgres user, you need to do that first. In WSL:

sudo -i -u postgres
psql
SET password_encryption = 'scram-sha-256';
\password postgres
\q
exit

Then try connecting from pgAdmin again with that password.

Verify PostgreSQL is listening on the right address

If you’ve edited the config files but connections still fail, check PostgreSQL’s listening address and port:

ss -tlnp | grep 5432

A localhost listener such as 127.0.0.1:5432 is expected for localhost access. For the direct WSL IP fallback, confirm the listener includes that interface and that the host rule permits the Windows source address.

Conclusion

You now have pgAdmin 4 on Windows connected to PostgreSQL in WSL. The main things to remember: start with localhost, use SCRAM authentication, and enable PostgreSQL startup if your distribution uses systemd.

If you want to practice SQL queries now, check out How to Use SQL Joins and Conditional Statements in PostgreSQL. And if you also use VS Code for development on WSL, How to Connect Visual Studio Code with WSL 2 for Linux Ubuntu is a useful companion setup.

Recommended for Linux builders

Contabo VPS hosting for Linux projects

Run Linux servers, automation tools, and self-hosted apps on a Contabo VPS with generous resources and predictable pricing.

Our customers sayExcellent4.6 out of 5 based on 11,008 reviews Trustpilot

Some links are affiliate links. This may earn LinuxBeast a commission at no extra cost to you.

Privacy settings

Choose which privacy controls to open.

Opening these controls does not change your saved choices.