pg_hba.conf file to allow remote connections, and ensuring your Windows firewall permits the traffic. By following these steps, you establish a secure bridge between the two environments without needing to log into the Linux subsystem directly.
Understanding the Network Boundary
By default, services running inside WSL are isolated from the Windows host. While WSL 2 uses a virtual switch to manage networking, the PostgreSQL server listening on localhost within the Ubuntu distro is not automatically reachable from Windows applications like pgAdmin. To fix this, you must treat the WSL instance as a remote server rather than a local one.
The primary challenge is that the IP address of your WSL distribution changes every time you restart it or reboot your computer. Therefore, hardcoding an IP address in your connection settings is unreliable. Instead, you should use the hostname localhost from the Windows perspective, which routes traffic through the NAT interface provided by Hyper-V or the WSL virtual switch.
Configuring PostgreSQL for Remote Access
Before attempting any network configuration, you must ensure the PostgreSQL service inside WSL accepts connections from outside its immediate environment. This involves editing two critical configuration files: postgresql.conf and pg_hba.conf.
Modifying postgresql.conf
First, open your terminal in WSL and locate the configuration directory. On most modern distributions, this is found in /etc/postgresql/[version]/main/. Open the postgresql.conf file using a text editor like nano or vim.
sudo nano /etc/postgresql/*/main/postgresql.confSearch for the listen_addresses directive. By default, it is often commented out or set to 'localhost'. Change this value to '*' to listen on all available network interfaces. This allows the database to accept connections from the Windows host via the loopback adapter.
listen_addresses = '*'Updating pg_hba.conf for Authentication
Next, you must configure who is allowed to connect. Open the pg_hba.conf file in the same directory.
sudo nano /etc/postgresql/*/main/pg_hba.confAdd a line at the end of the file to permit IPv4 local connections. It is crucial to use a secure authentication method such as scram-sha-256 or md5 (if legacy compatibility is required, though scram is preferred). Avoid using trust unless you are in a strictly isolated development environment, as this bypasses password verification entirely.
host all all 127.0.0.1/32 scram-sha-256If you want to allow connections from other devices on your local network, you can replace 127.0.0.1/32 with 0.0.0.0/0, but restrict this only if necessary. After saving both files, restart the PostgreSQL service inside WSL to apply the changes:
sudo service postgresql restartHandling Windows Firewall Rules
Even with correct PostgreSQL configuration, Windows Defender Firewall may block incoming connections on the port PostgreSQL uses (default 5432). You need to create an inbound rule to allow this traffic.
- Open the Windows Security app and navigate to Firewall & network protection.
- Select Advanced settings to open the Windows Defender Firewall with Advanced Security console.
- Right-click on Inbound Rules and select New Rule....
- Choose Port and click Next.
- Select TCP and enter
5432in the Specific local ports field. - Allow the connection and apply it to Domain, Private, and Public profiles.
- Name the rule something identifiable, such as
WSL PostgreSQL Access.
This step ensures that the packet traveling from pgAdmin on Windows reaches the WSL virtual switch without being dropped by the host OS.
Connecting via pgAdmin
With the backend configured and the firewall open, you can now add the server in pgAdmin on Windows.
- Open pgAdmin and right-click on Servers in the browser tree.
- Select Create > Server.
- In the General tab, give the server a name, such as
WSL Postgres. - Navigate to the Connection tab.
- Set the Host name/address to
localhost. This is the key trick; from Windows,localhostpoints to the WSL virtual adapter. - Set the Port to
5432. - Enter the Maintenance database (usually
postgres) and your username/password.
If the connection fails, verify that the WSL instance is actually running by executing wsl in PowerShell. If the IP address has changed, localhost still works because the NAT mapping handles the translation dynamically. For more details on managing WSL connectivity, see Troubleshooting SSH WSL Machine: Can't Connect to Localhost.
Troubleshooting Common Issues
If you cannot connect, first check if PostgreSQL is listening on the correct address inside WSL by running netstat -tuln | grep 5432. Ensure the output shows 0.0.0.0:5432 or *:5432, not just 127.0.0.1:5432. Additionally, verify that your Windows firewall rule is active and that no third-party antivirus software is blocking the connection. If you are moving data between systems, you might also find it useful to Mounting Windows Folder in WSL (Debian) using fstab for easier file access during debugging.
Frequently Asked Questions
Why does my WSL IP address keep changing?
WSL 2 runs inside a lightweight utility VM managed by Hyper-V, which reassigns dynamic IP addresses upon restart. This is why you should always connect using localhost from Windows rather than a static IP, as the NAT layer handles the routing transparently.
Is it safe to use md5 authentication?
While md5 is widely supported, it is considered weaker than scram-sha-256. If your PostgreSQL version supports it, prefer scram-sha-256 for better security against password sniffing attacks. Only use md5 if you have older clients that do not support SCRAM.
Can I connect to WSL PostgreSQL from another computer on my network?
Yes, but you must change the listen_addresses in postgresql.conf and update pg_hba.conf to allow connections from your subnet (e.g., 192.168.1.0/24). You will also need to create additional firewall rules on Windows to allow inbound traffic from those external IPs.
What if pgAdmin says "Connection refused"?
This usually means PostgreSQL is not running inside WSL or is not listening on the expected port. Verify the service status with sudo service postgresql status and ensure you have restarted the service after modifying postgresql.conf to apply the new listen addresses.
Do I need to install PostgreSQL inside WSL?
No, you can use the native Windows installer for PostgreSQL and connect to it from WSL, or vice versa. However, keeping the database inside WSL is common for developers working primarily in Linux environments who want to maintain parity with production servers.