Solve WSL2 Port Binding Issue
Published on April 08, 2025
2 MINS READ
Recently, I have been developing the Xuanji Assistant, and the development environment is WSL2 on Windows 11. Sometimes, when I running , I find that http://localhost:8000 is inaccessible. By using the command to check the port usage, I discovered that the port is not occupied.
This issue can sometimes be resolved by restarting, but it reappears after a while, which is quite confusing. Because every time this problem occurs, when checking which programs are occupying the port with , it shows that no program is occupying it.
This issue only occurs on my Windows devices. There is no such problem on macOS. I initially suspect it might be a problem with the WSL2 development environment.
Regarding Windows ports and Hyper-V:
- Windows has a dynamic TCP port range, within which ports are occupied by some system services. Before Windows Vista, this range was 1025-5000; after Windows Vista, it is 49152-65535.
- If Hyper-V is installed on Windows, Hyper-V will occupy random ports within the aforementioned range.
To check the dynamic port usage, use the command . It was found that port 8000 is within the dynamic port range. Please note that ports within the dynamic port range are in a ready-to-use state, not occupied. The currently occupied ports can be queried using the command .
Great. It seems that the dynamic port range has been modified. This system has been in use for over a year and has been kept updated all the time. It's very difficult to find out when it was modified. Let's just change it back directly.
After modification and restart, the problem was solved.
Afterword
Due to my system cleanliness obsession, I reinstalled the Windows 11 system two weeks later, with the version being 24H2 from March 2025. I executed the command again:
It can be seen that the default dynamic port range is already 49152-65535, and the problem of port occupation has not occurred again.
References
Tags:
#WSL2
#Hyper-V