I've migrated three different teams from Docker Desktop to Podman Desktop, and it never goes as smoothly as the documentation promises. Here's what actually happens and how to survive it without losing your sanity or your job.
Pre-Migration Reality Check
Before you start, accept these truths:
- Something will break in a way you didn't expect
- At least one developer will have a weird setup that takes 3 hours to debug
- The person who volunteers to go first will become tech support for everyone else
- You'll spend more time on permissions issues than actual migration
Study the common migration issues, read through migration war stories, and check what actually breaks most often. Most problems are permission-related or networking bullshit that the docs don't warn you about.
Backup your shit first:
## Don't be the person who loses everyone's database
docker ps -a > running_containers.txt
docker volume ls > volumes_backup.txt
docker network ls > networks_backup.txt
## Copy your compose files to a safe place
The team conversation you need to have:
"We're doing this migration. It should take 2 hours. It will probably take 4. If you have a weird setup, it might take all day. Yeah, I know it's annoying, but we're doing it anyway because paying Docker $50k/year is stupid."
Phase 1: The "Simple" Preparation (Actually 30-45 Minutes)
What the docs say: "Export your containers and stop Docker Desktop"
What actually happens:
mkdir ~/docker-migration-backup || sudo mkdir ~/docker-migration-backup
## This command looks simple but takes forever if you have large containers
docker ps -aq | xargs -I {} docker export {} > ~/docker-migration-backup/{}.tar
## Don't forget your actual project files (the important stuff)
cp -r ~/dev/my-important-project ~/docker-migration-backup/
Stopping Docker Desktop (The Gotcha):
- Docker Desktop doesn't actually stop when you quit it - it keeps running background services
- On Mac: Activity Monitor → find all
docker and com.docker processes → kill them with prejudice
- On Windows: Task Manager → End all Docker processes → pray it doesn't restart automatically
- The daemon socket at
/var/run/docker.sock might still exist and confuse everything
Phase 2: Podman Installation (20 Minutes If You're Lucky)
The download part is easy:
- Go to podman-desktop.io/downloads
- Download the installer and hope it's not a broken release
- Run installer as admin (because everything needs admin on corporate laptops)
- Launch Podman Desktop and watch it immediately crash
What actually happens during setup:
- The installer works fine but Podman Desktop won't start because of security policies
- macOS will complain about unsigned developers (click "Open Anyway" in Security settings)
- Windows Defender will quarantine half the files for no reason
- The initial setup wizard assumes you know what a "machine" is in Podman context (you don't)
Commands that might work:
## This should show a version but might show "command not found"
podman --version
## This will fail with permission errors the first time
podman run hello-world
## Error: cannot connect to Podman socket: Permission denied
## Fix the permission bullshit (macOS/Linux)
sudo usermod -aG docker $USER
## Wait, there's no docker group for Podman. Google "podman rootless permissions"
## Eventually this works
podman run hello-world
Phase 3: The Part Where Everything Breaks (1-3 Hours)
The Docker Compose switcheroo:
## This looks simple but will fail in creative ways
podman-compose -f docker-compose.yml up
## Error: podman-compose: command not found
## Install podman-compose (forgot this step)
pip3 install podman-compose
## Error: pip3 not found (because Python is a mess)
## Eventually get podman-compose working
podman-compose -f docker-compose.yml up
## Error: network "default" not found
## Error: port 80 permission denied (rootless containers can't bind <1024)
## Error: volume mount failed (SELinux/permissions again)
The nuclear option (what actually works):
## Alias docker to podman for your sanity
echo "alias docker='podman'" >> ~/.bashrc
echo "alias docker-compose='podman-compose'" >> ~/.bashrc
source ~/.bashrc
## Now your old commands work (mostly)
docker run hello-world # actually runs podman
docker-compose up # actually runs podman-compose
What you'll spend 2 hours debugging:
- Port 80 won't bind because rootless containers can't use privileged ports
- Volume mounts fail with cryptic permission errors
- Networks don't exist and need to be recreated manually
- That one service that worked fine in Docker Desktop now gets "connection refused"
Phase 4: The 3AM Debugging Session (When It All Goes Wrong)
The port binding clusterfuck:
Your app tries to bind to port 80 and Podman says "permission denied." Rootless containers can't bind to ports under 1024. Fix it:
## Option 1: Use unprivileged ports in your compose file
## Change "80:80" to "8080:80" everywhere
## Option 2: Enable rootless port binding (Linux only)
echo 'net.ipv4.ip_unprivileged_port_start=80' | sudo tee /etc/sysctl.d/podman.conf
sudo sysctl -p /etc/sysctl.d/podman.conf
## Option 3: Use host networking (breaks container isolation but works)
podman run --network=host nginx
The volume mount permission hell:
Your database won't start because volume permissions are fucked. SELinux and file ownership will ruin your day:
## Check what's actually happening
ls -la /path/to/your/volume
## drwxr-xr-x 1 root root # ← this is your problem
## Fix ownership (the nuclear option)
sudo chown -R $USER:$USER /path/to/your/volume
## SELinux fix (Red Hat/Fedora)
podman run -v /host/path:/container/path:Z myimage # ← the :Z is magic
When your IDE stops working:
VS Code Docker extension doesn't know Podman exists. Either configure it manually or just use the terminal like a real developer.
Murphy's Law: Everything That Can Break Will Break
The dreaded "network not found" error:
podman-compose up
## Error: network "myproject_default" not found
## Create the network manually (what you'll spend an hour figuring out)
podman network create myproject_default
## Now it works, but only until you restart your machine
When containers can't talk to each other:
Docker Desktop's networking "just worked" but Podman is more strict about network isolation. Your API calls start failing:
## Debug container networking
podman network ls
podman inspect <container_name> | grep NetworkMode
## The sledgehammer approach that usually fixes it
podman-compose down
podman network prune
podman-compose up # recreates everything
Database containers losing data:
Your Postgres container starts clean every time, panic ensues:
## Check if your volume actually exists
podman volume ls
## postgres_data doesn't exist
## Recreate with the exact same name as before
podman volume create postgres_data
## Copy your backup data back
After migration, your laptop will feel like you upgraded the hardware:
- Docker Desktop: 8-12GB RAM idle, fans constantly running, 30+ second container startup
- Podman Desktop: Maybe 1.5-2GB RAM idle, laptop actually sleeps, containers start in 2-5 seconds
- OrbStack: Around 1GB RAM idle, containers start fast as hell
- Container startup: Way faster than Docker Desktop - like night and day difference
- File sync: Actually works in real-time instead of Docker Desktop's annoying delays
- CPU usage: Way less background bullshit when idle
- Battery life: Several hours longer on laptops when running containers
The Migration Survivor's Guide
What actually works after migration:
- Your containers run faster and use less memory
docker commands work fine with aliases- Compose files work with minor tweaks
- Your laptop stops sounding like it's mining Bitcoin
What you'll miss from Docker Desktop:
- Honestly? Nothing important. The GUI was slow and the Kubernetes integration was fake.
What you'll tell other developers:
"Why the hell were we paying for Docker Desktop? This should have been free from the beginning."
The reality is that 90% of migrations go fine. The other 10% involve someone with a Frankenstein development setup who mounted 47 volumes and used custom networking that broke in creative ways. Don't be that person.
