Ubuntu 20.04 WSL 1: UI Can't Run

The error occurs because WSL 1 lacks a full Linux kernel, preventing dynamic linker resolution of Qt5 shared libraries like libQt5Core.so.5. The definitive solution is to upgrade your distribution to WSL 2, which provides the necessary kernel support for native library loading and UI execution.

Understanding the Root Cause

The specific error message regarding libQt5Core.so.5 indicates that the system cannot locate or load a critical component of the Qt5 framework. While this might appear to be a missing package issue, the underlying cause is architectural. Windows Subsystem for Linux version 1 (WSL 1) operates by translating Linux system calls into Windows NT kernel calls. It does not run a real Linux kernel. Consequently, many complex shared objects, particularly those involving graphical interfaces or advanced memory management features required by modern Qt applications, fail to initialize correctly. When you attempt to run a UI tool compiled against Qt5, the dynamic linker (ld-linux-x86-64.so.2) searches for the required .so files. In WSL 1, even if the file exists on the filesystem, the translation layer often fails to map the dependencies correctly, resulting in the "No such file or directory" error despite the file being present. This is a known limitation of the older architecture. Upgrading to WSL 2 resolves this by introducing a lightweight virtual machine running a real Linux kernel, allowing standard Linux library resolution to function as expected. For users who have recently set up their environment, understanding where your installation resides is crucial before attempting any migration steps. You can verify your current setup by checking your installation location, as detailed in our guide on Ubuntu WSL Install Location: Where to Find It?. This ensures you are targeting the correct distribution instance during the export and reimport process.

Why Package Installation Fails

A common misconception is that reinstalling Qt packages will fix the issue. Running commands like sudo apt install qtbase5-dev or sudo apt-get install libqt5core5a will likely succeed without errors. However, the binary will still crash upon execution because the problem is not the absence of the file, but the inability of the WSL 1 environment to execute it properly. The dynamic linking process requires kernel-level interactions that WSL 1 simply does not support for these types of libraries. Therefore, software updates and dependency fixes are ineffective remedies for this specific symptom.

Step-by-Step Migration to WSL 2

To resolve the UI execution failure, you must migrate your Ubuntu 20.04 distribution from WSL 1 to WSL 2. This process involves exporting the current state of your Linux distro, deleting the old version, and importing it back with the new architecture. Follow these steps carefully to ensure no data is lost.

1. Export the Distribution: Open PowerShell as Administrator on your Windows host. Use the following command to export your Ubuntu 20.04 instance to a tar archive. Replace Ubuntu-20.04 with the actual name of your distribution if it differs.

wsl --export Ubuntu-20.04 C:\wsl-backup\ubuntu2004.tar

This creates a backup file at the specified path. Ensure you have sufficient disk space for this operation, as it copies all your installed packages and user data.

2. Unregister the Old Instance: Once the export is complete, unregister the existing WSL 1 instance. This removes the old configuration but keeps your exported tar file safe.

wsl --unregister Ubuntu-20.04

You may receive a confirmation prompt; confirm the action. Your previous Ubuntu installation will no longer appear in the list of running distributions.

3. Import as WSL 2: Now, import the tar file back into WSL, explicitly specifying version 2. This step converts the architecture.

wsl --install -d Ubuntu-20.04 --version 2

If the automatic install command fails due to network issues or other constraints, you can use the generic import command:

wsl --import Ubuntu-20.04 C:\WSL\Ubuntu2004 C:\wsl-backup\ubuntu2004.tar --version 2

This command places the root filesystem in C:\WSL\Ubuntu2004 and loads the data from your backup. The --version 2 flag is critical; omitting it defaults to WSL 1.

4. Verify the Upgrade: Launch your terminal and check the version.

wsl -l -v

Your Ubuntu 20.04 entry should now show VERSION 2. You can now launch your UI tools, and the libQt5Core.so.5 error should be resolved.

Alternative Considerations

If migrating to WSL 2 is not immediately possible due to hardware limitations or specific enterprise policies requiring WSL 1, you may need to reconsider your development environment. For instance, if you are working with heavy data processing or require cross-machine consistency, some users explore transferring their WSL Ubuntu installation to USB drives for portability, though this also benefits significantly from WSL 2 capabilities as discussed in Can I Transfer My WSL Ubuntu Installation to a USB and Run It from There?. Another alternative is to use a remote desktop protocol. Instead of trying to run GUI apps directly in WSL, you can install a VNC server or RDP service on the Linux side and connect from Windows. This bypasses the local library loading issue entirely by rendering the display over the network. However, this introduces latency and is generally less performant than native WSL 2 integration. It is also worth noting that if you are using newer hardware, such as Windows 11, cloning your distro is a straightforward way to test environments safely. As outlined in Clone WSL Distro: Installing Ubuntu on WSL2 in Windows 11, creating clones allows you to experiment with different configurations without risking your primary workspace. This practice is highly recommended when performing major architectural changes like the WSL 1 to WSL 2 migration described above.

Frequently Asked Questions

Can I fix the Qt5 error by installing libqt5core5a manually?

No, installing the package will not solve the problem in WSL 1. The error stems from the lack of a real Linux kernel, not missing files. Even if the library is present, the WSL 1 translation layer cannot execute it correctly. You must upgrade to WSL 2 to enable proper dynamic linking.

Does upgrading to WSL 2 affect my existing files and settings?

Your files and settings are preserved if you follow the export-import method correctly. By using wsl --export before unregistering, you create a complete snapshot of your environment. When you import it back with --version 2, all your user accounts, installed packages, and configurations are restored exactly as they were.

Is WSL 2 supported on all versions of Windows?

WSL 2 requires Windows 10 version 1903 or higher, or Windows 11. If you are on an older version of Windows 10, you may need to update your OS first. Additionally, certain older hardware without virtualization support enabled in the BIOS cannot run WSL 2. Check your system specifications to ensure compatibility before proceeding with the migration.

What if I cannot upgrade to WSL 2 due to work restrictions?

If organizational policies prevent WSL 2 usage, consider running your GUI applications on a separate virtual machine or cloud-based Linux instance. You can then access the interface via Remote Desktop Protocol (RDP) or VNC. This approach isolates the GUI requirements from your WSL 1 development environment, avoiding the library loading conflicts entirely.

How do I verify that my WSL instance is actually running version 2?

Open a Command Prompt or PowerShell window and type wsl -l -v. Look for your Ubuntu distribution in the list. The column labeled "VERSION" should display "2". If it shows "1", the migration was not successful, and you should repeat the unregister and import steps carefully.