Users often struggle to connect to a MySQL database from within Windows Subsystem for Linux (WSL) while external connections succeed. This guide resolves the issue by addressing network routing differences in WSL2, verifying firewall rules on Windows 11, and correcting MySQL bind-address configurations to ensure local host access works reliably.
Understanding WSL2 Network Architecture
The core of this problem lies in how WSL2 manages networking compared to traditional virtual machines or direct installations. Unlike earlier versions, WSL2 runs inside a lightweight utility VM with its own private NAT network. When you attempt to connect to
localhost or
127.0.0.1 from inside WSL, you are not connecting to the Windows host's loopback interface. Instead, you are connecting to the WSL instance's own internal loopback, which does not have the database server running unless it is installed directly inside Linux.
This architectural shift means that standard connection strings using
localhost will fail if the database is hosted on the Windows side. You must identify the actual IP address of your Windows host machine to establish a bridge between the two environments. The most reliable method is to determine the IP address assigned to your Windows Wi-Fi or Ethernet adapter from within the WSL terminal. You can achieve this by running
ipconfig on the Windows PowerShell or Command Prompt and looking for the IPv4 address under your active network adapter. Alternatively, you can find the gateway IP from inside WSL by executing
cat /etc/resolv.conf, which typically lists the Windows host as the nameserver.
Configuring MySQL Bind Address
Even with the correct IP address, MySQL might reject connections if it is configured to listen only on specific interfaces. By default, many MySQL installations restrict listening to
127.0.0.1 for security reasons. However, because WSL2 sees the Windows host as a remote machine via its NAT gateway, you may need to adjust these settings. If you are experiencing issues similar to those described in our guide on
Resolving Connection Issues with Ubuntu's WSL2 and MySQL: Changing bind-address in /etc/mysql/mysql.conf.d/mysqld.cnf, you should inspect the MySQL configuration file.
Locate the
mysqld.cnf file, usually found in
/etc/mysql/mysql.conf.d/ on Linux hosts or
C:\ProgramData\MySQL\MySQL Server X.X\my.ini on Windows. Look for the
bind-address directive. If it is set to
127.0.0.1, change it to
0.0.0.0 to allow connections from any interface, including the WSL2 network interface. After making this change, restart the MySQL service on Windows using the Services manager or the command line. It is crucial to note that opening MySQL to all interfaces has security implications; ensure that strong passwords are used and that firewalls restrict access to trusted networks only.
Verifying Windows Firewall Rules
Once the network path and MySQL configuration are aligned, the next potential blocker is the Windows Firewall. Windows 11 includes robust firewall protections that may block incoming connections on port 3306 (the default MySQL port) from unknown sources, including the WSL2 virtual switch. You need to create an inbound rule that explicitly allows traffic on port 3306.
Navigate to the Windows Defender Firewall with Advanced Security console. Create a new Inbound Rule, select "Port," and specify TCP port 3306. Allow the connection for all profiles (Domain, Private, Public) to ensure stability regardless of your network location. Name the rule clearly, such as "Allow MySQL WSL2 Access." This step ensures that packets originating from the WSL2 NAT network are not dropped before reaching the MySQL process. For further troubleshooting on network connectivity between WSL and Windows, you might also want to check out
How to Ping WSL2 Ubuntu from Windows Host to confirm basic layer-3 connectivity.
Testing the Connection
After adjusting the bind address and firewall rules, test the connection from within your WSL terminal. Use the MySQL client command, replacing the IP address with the one you identified earlier. The command should look like this:
mysql -h <WindowsHostIP> -u root -p. If the connection succeeds, you will see the MySQL prompt. If it fails, verify that the MySQL service is actually running on Windows by checking the services list. Additionally, ensure that no other antivirus software is intercepting the connection on port 3306.
If you continue to face difficulties, consider whether your database is actually running on Windows or if it is installed inside WSL itself. If the database is native to WSL, you should connect using
localhost or
127.0.0.1 without modifying Windows firewall rules. Understanding where the service resides is key to applying the correct fix.
Frequently Asked Questions
Why does localhost work outside WSL but not inside?
In WSL2, localhost refers to the virtual machine's own loopback interface, not the Windows host. Since the database runs on Windows, connecting to localhost inside WSL attempts to reach a non-existent service on the Linux side. You must use the Windows host's actual IP address instead.
Is it safe to change bind-address to 0.0.0.0?
While necessary for cross-platform connectivity, setting bind-address to 0.0.0.0 exposes MySQL to all network interfaces. You should mitigate risks by configuring strong authentication, limiting user privileges, and ensuring your Windows Firewall only allows connections from trusted subnets, such as the WSL2 private network.
How do I find my Windows IP address from WSL?
You can find the Windows host IP by running
cat /etc/resolv.conf inside WSL and looking for the nameserver entry. Alternatively, run
ipconfig in Windows PowerShell and copy the IPv4 address of your active network adapter.
What if I cannot connect even after changing the IP?
Check the Windows Firewall to ensure an inbound rule exists for TCP port 3306. Also, verify that the MySQL service is running on Windows and that there are no conflicting antivirus programs blocking the port. Restarting both the MySQL service and the WSL instance (
wsl --shutdown) can help reset network states.
Can I use Docker containers in WSL for this setup?
Yes, but Docker Desktop integrates differently with WSL2. If you are using Docker, ensure that the container is exposed to the host network correctly. For complex setups involving containers, refer to resources on
MySQL Server Won't Connect to Docker Container on Ubuntu 22.04 to understand container networking nuances.