You switched from Docker to Podman and your containers vanished
You installed Fedora, noticed Docker was no longer in the official repositories, and switched to Podman. You ran dnf install podman, pulled a few images, and tried to start your old containers. The terminal prints a storage error instead of a running process. Your containers exist on disk, but Podman refuses to see them. You need to translate the old Docker storage layout into Podman's format without losing your data or layers.
What's actually happening under the hood
Docker and Podman share a common ancestor, but they manage container storage differently. Docker relies on a central daemon that writes metadata to a SQLite database and stores layers in a specific directory tree. Podman is daemonless. It uses containers-storage to track images, containers, and volumes through a set of JSON files and a separate lock mechanism. Both tools often use the overlay filesystem driver, but the metadata paths, registry configurations, and lock file structures do not match.
When you run podman without migrating, it scans its own storage directories, finds nothing, and assumes your containers do not exist. The migration command reads the old Docker metadata, converts the layer references, updates the registry configuration, and writes everything into Podman's native format. The process does not copy the actual filesystem layers. It only rewrites the pointers and metadata so Podman can mount the existing overlay directories correctly.
Run the migration before you pull new images. Mixing storage backends on the same machine will cause layer duplication and wasted disk space.
The fix or how-to
Stop all running containers first. A live container holds open file descriptors to its overlay mounts. Forcing a migration while layers are mounted will corrupt the metadata. Run systemctl stop docker if the daemon is still active, or use docker stop to halt them gracefully.
# Stop the Docker daemon to release file locks on the storage directory
sudo systemctl stop docker
# Halt all running containers and wait for them to exit cleanly
sudo docker stop $(sudo docker ps -q)
Run the migration command next. This reads the Docker storage backend and writes the equivalent Podman metadata. The command is idempotent, so running it twice will not duplicate your data.
# Translate Docker's SQLite metadata and layer references into Podman's JSON format
sudo podman system migrate
Fedora ships Podman with a default lock configuration that works for most workloads. If you previously edited /etc/containers/containers.conf to increase the maximum number of locks, the migration will carry over the old limit. Podman expects lock numbers to match the new container IDs. Run the renumber command immediately after migration to align the lock files with the migrated containers.
# Reassign lock file numbers to match the newly migrated container IDs
sudo podman system renumber
Convention aside: Always edit configuration files in /etc/containers/. The files in /usr/share/containers/ ship with the podman package and will be overwritten on the next dnf upgrade. If you need to adjust storage drivers or lock limits, create or modify /etc/containers/storage.conf and /etc/containers/containers.conf. Restart your terminal session after changing these files so the new environment variables take effect.
Rootless migration requires a different approach. Docker stores data in /var/lib/docker. Podman rootless stores data in ~/.local/share/containers. The migration command cannot cross these permission boundaries. You must run sudo podman system migrate to access the root storage directory. If you want to run containers as a regular user after migration, export the containers and import them into your rootless namespace, or adjust the ownership of the migrated storage directory.
# Change ownership of the migrated storage directory to your regular user
sudo chown -R $USER:$USER ~/.local/share/containers
# Verify the new permissions match your rootless Podman configuration
ls -la ~/.local/share/containers/storage
Run the migration as root first. Switch to rootless operation only after the metadata is safely converted.
Verify it worked
Check the container list and image registry. The output should show your old containers with their original names and IDs.
# List all containers to confirm they survived the metadata translation
sudo podman ps -a
# Verify that your pulled images are recognized by the new storage backend
sudo podman images
If the lists are empty, the migration did not complete. Check the journal for storage errors before retrying. Run journalctl -xeu podman to see the exact failure point. The x flag adds explanatory context to each log line, and the e flag jumps to the end of the buffer. Read the actual error before guessing.
Verify the storage driver matches your system capabilities. Podman will fall back to vfs if it cannot detect native overlay support, which drastically reduces performance and increases disk usage.
# Display the active storage driver and graphroot path
podman info --format '{{.Store.GraphDriverName}}'
# Check the overlay mount options to ensure metacopy is enabled
podman info --format '{{.Store.GraphOptions}}'
Reboot before you debug storage driver mismatches. Half the time the kernel module just needs to reload.
Common pitfalls and what the error looks like
The most frequent failure happens when users run the migration as a rootless user while the original Docker containers were created as root. Docker stores data in /var/lib/docker. Podman rootless stores data in ~/.local/share/containers. The migration command cannot cross these permission boundaries. You must run sudo podman system migrate to access the root storage directory.
Another common issue involves the overlay storage driver. If your system uses fuse-overlayfs instead of native overlay, the migration might fail with a driver mismatch error. The terminal will print Error: driver not supported: overlay. This happens when the kernel module is missing or the filesystem does not support the required features. Install the fuse-overlayfs package and update /etc/containers/storage.conf to set driver = "fuse-overlayfs" before retrying.
Lock file exhaustion is the third major trap. Podman uses a lock file to prevent concurrent operations from corrupting the storage database. If you see Error: too many open files or EAGAIN: resource temporarily unavailable, your system limit for file descriptors is too low. Run ulimit -n to check the current limit. Increase it to at least 1048576 in /etc/security/limits.conf and restart your session.
Error: cannot lock the database: resource temporarily unavailable
The error above means the lock manager cannot acquire a file descriptor. It is not a Podman bug. It is a system limit. Adjust the descriptor limit and run podman system renumber again.
SELinux denials also interrupt migration on enforcing systems. The migration process writes new JSON files into the storage directory. If the context labels do not match, the operation fails silently or prints a permission denied message. Check the audit log before disabling SELinux.
# Search for recent SELinux denials related to podman or containers
sudo ausearch -m avc -ts recent | grep -i podman
# Restore correct context labels on the storage directory
sudo restorecon -Rv ~/.local/share/containers
Trust the package manager. Manual file edits drift, snapshots stay.
When to use this vs alternatives
Use podman system migrate when you are switching from Docker to Podman on the same machine and want to preserve your existing containers and images. Use podman system reset when you want to wipe all local containers, images, and volumes to start with a clean storage backend. Use docker export and podman import when you only need the container filesystem and do not care about preserving the original image layers or metadata. Use skopeo copy when you want to transfer images between registries without pulling them into local storage first. Stay on the default overlay driver if your filesystem supports it and you want the best performance. Switch to vfs only when debugging storage corruption on unsupported filesystems.