Docker Compose to Podman Quadlet: A Practical Migration Guide

If you run Podman and you've typed podman generate systemd lately, you got a warning telling you to use Quadlet instead. Nothing broke. The command still works, and the maintainers have said they won't remove it. But it's frozen: no new features, only urgent bug fixes, while the whole ecosystem moves to Quadlet. If you run containers on a server and want them to survive reboots, this is worth doing properly once.

The official Podman docs mark generate systemd deprecated: no plans to remove it, but only urgent bug fixes, no new features. In a containers/podman GitHub Discussion, a maintainer explains the strategy directly: no new features will be added to generate systemd, and Quadlet aims for a Compose-and-Kubernetes-like declarative workflow instead. Quadlet became the recommended path once merged into Podman 4.4, which already shipped to CentOS Stream and Fedora, so this isn't an experimental feature you'd be migrating to early.

A Quadlet is a small text file that looks like a systemd unit but is written in Podman's shorthand. You drop a file ending in .container into the right directory, run a daemon-reload, and systemd's Podman generator turns it into a real .service unit on the fly.

You never edit the generated service directly. You edit the short Quadlet file and reload. When Podman updates, the generated service updates with it automatically. That's the whole point, and it's exactly why the old generate-a-static-file approach is going away: a static generated .service file doesn't know when Podman's own defaults change underneath it.

Let's convert a real stack instead of a single podman run command, since that single-container case is already well covered elsewhere. Say you have this docker-compose.yml running a Caddy web server in front of a PostgreSQL database, on a shared network, with a named volume for the database data.

In Quadlet land, one compose file becomes several unit files. That feels like more work at first. It pays off because each piece is independently managed by systemd: you can restart the database without touching the web server's unit, and systemctl status tells you exactly which piece is unhealthy instead of one opaque compose stack.

Don't hand-write all of this if you don't have to. podlet is a Rust CLI, roughly 1.5k GitHub stars, that reads a compose file and generates Quadlet units:

It's a good starting point and saves typing. It's also not complete. Its own docs are blunt about it: if podlet hits an unsupported compose option, it errors out and you have to comment that option out to continue. And in a real multi-service compose file with no explicit network defined, podlet has been reported to generate no .network file at all, silently leaving Quadlet to fall back to separate default networks per container so they can't reach each other.

Treat podlet's output as a scaffold, not a finished config. Read every generated file line by line, and specifically check that a .network unit exists and is referenced by every container that needs to talk to the others.

Most self-hosted setups should default to rootless unless a specific container genuinely needs root or a privileged port. If you're validating your compose file's health checks before making this move, our ComposeHealthCheck tool can catch missing depends_on conditions and healthcheck issues in your existing Docker Compose setup first.

Once it's running, you have containers that start on boot, restart on failure, order themselves correctly via Requires=/After=, and log to one place, without a daemon and without root. That's a better deal than the compose setup you started with, and it's where Podman is going.

If part of what you're migrating off cron also includes scheduled jobs rather than long-running services, our Cron to systemd Timer Converter handles the other half of the systemd migration: paste a crontab line and get a ready-to-save .timer and .service pair.