Migrating Docker from Windows 11 and WSL2 to Linux: What I Learned

In short: When I switched from Windows to Linux, installing the new system was the easy part. The real work was moving my Docker environment from Windows 11 with WSL2. My most important advice: distinguish between what can be rebuilt and what is irreplaceable. Back up databases additionally as a dump, and a backup is only worth something once the restore has been tested.

The starting point

On Windows 11, my development environments ran in Docker Desktop with WSL2. Over the years, images, containers, volumes, databases and project data for various client projects had piled up. Much of it could no longer be rebuilt in five minutes. So I needed a plan.

First understand what is really stored

With Docker, three things are often mixed up:

• Images can usually be rebuilt from a Dockerfile or pulled from a registry.
• Containers are short-lived instances and can be recreated at any time.
• Volumes and other persistent data are often what is really valuable: databases, uploads and locally stored application data.

That's why a migration should not start by blindly copying some Docker directory. First you need to find out which data lives where and which versions are actually in use.

My approach

I followed a simple order:

1. Record all projects, Compose files and environment variables.
2. Export important databases additionally as a dump, for example with mysqldump or mariadb-dump.
3. Back up persistent files and volumes separately.
4. Set Docker up again on Linux.
5. Start containers with known versions and restore the data in a controlled way.
6. Check applications and data before shutting down the old system.

Depending on the project, the order may differ. But never copy database directories carelessly between different database versions.

Why WSL2 is not a normal directory

On Windows, Docker Desktop's Linux containers run in their own Linux environment. That leads to false expectations: just because you can find or export files from Windows, the structure on a new Linux system is far from identical.

Typical pitfalls:

• Paths: a bind mount that pointed to a certain folder on Windows needs a different path on Linux.
• Users and permissions: on Linux, user IDs, groups and file permissions play a much more direct role. Files created by a container suddenly belong to a different user.
• Network: ports, hostnames and local domains can behave differently.
• Line endings and scripts: shell scripts edited on Windows should be checked for Windows line endings.

For projects with many configuration files, a systematic review pays off instead of waiting for errors.

Databases deserve special care

Anyone who looks after Shopware or Symfony projects knows: a database is not an interchangeable container. A lost volume can cost hours or days of work.

For important data I therefore consider a dump in addition to the file backup worthwhile. A dump can be restored specifically into a matching database instance. You need to watch database version, character set, collation and the application's requirements. Shopware, for example, has clear requirements for which MySQL or MariaDB versions are supported.

What I do differently today

The move strengthened my resolve to keep development environments as reproducible as possible:

• Compose files and configuration belong in a traceable project structure.
• Credentials don't belong in the repository.
• Persistent data needs its own backup concept.
• Database and PHP versions are pinned in the configuration, not "latest".

And above all: a backup is only reassuring once the restore has been tested.

Conclusion

Switching from Windows to Linux was not the problem. The Docker environment that had grown over the years was the real challenge. If you distinguish early between configuration, reproducible images and irreplaceable data, you save yourself a lot of stress.

The most important lesson applies regardless of the operating system: documentation and tested backups beat any spontaneous copy job.

Frequently asked questions

Can I simply copy Docker volumes from WSL2 to Linux?

Technically, volumes can be backed up and restored. For databases, though, a dump is the safer route, especially if the database version might change.

Do I need to rebuild my images?

If there is a Dockerfile, rebuilding is usually the cleanest way. Images from a registry you simply pull again.

What is the most common mistake when moving?

In my experience: overlooking persistent data because you only think about containers and images. Only a complete inventory prevents that.