{"id":167951,"date":"2026-05-23T18:41:07","date_gmt":"2026-05-23T15:41:07","guid":{"rendered":"https:\/\/computingforgeeks.com\/?p=167951"},"modified":"2026-05-24T00:43:16","modified_gmt":"2026-05-23T21:43:16","slug":"podman-quadlet-systemd-fedora","status":"publish","type":"post","link":"https:\/\/computingforgeeks.com\/podman-quadlet-systemd-fedora\/","title":{"rendered":"Run Podman Quadlet Systemd Containers on Fedora 44 \/ 43 \/ 42"},"content":{"rendered":"\n

If you have ever run a container long-term with podman run -d<\/code>, you have written a deployment with no lifecycle, no logging integration, and no obvious way to restart on host reboot. Quadlet is Podman’s answer to that gap: drop a small declarative file in the right systemd directory, run systemctl daemon-reload<\/code>, and Podman generates a proper systemd unit that integrates with the journal, supports restart<\/code> policies, plays nicely with systemctl enable<\/code>, and survives reboots cleanly. Both rootful and rootless flavors work the same way.<\/p>\n\n\n\n

This guide walks through running Podman 5 containers as systemd services on Fedora 44 using Quadlet. You will deploy a real Nginx container as a rootful systemd unit, a Caddy container as a rootless unit under your own user, see the generated systemd unit, and walk through the additional Quadlet file types (.network, .volume, .build, .pod) that compose into multi-container deployments. The same syntax works on Fedora 43 and Fedora 42 because Podman 5 has shipped as the default on every release since F40. Container basics like image pulls and image listing come from the DNF5 cheatsheet<\/a> install path that gives you Podman.<\/p>\n\n\n\n

Verify Podman 5 ships Quadlet<\/h2>\n\n\n\n

Quadlet has been part of the Podman package since Podman 4.4 and became the recommended deployment style starting with Podman 5. Fedora 44 ships Podman 5.8.x as the default; no extra install required:<\/p>\n\n\n\n

podman --version\nrpm -q podman containers-common\nls \/usr\/libexec\/podman\/quadlet<\/code><\/pre>\n\n\n
The third command is the proof that Quadlet is actually present on disk; it is the binary the systemd generator invokes when it sees a .container<\/code> file. Expected output on F44 is:<\/p>\n\n\n
podman version 5.8.2\npodman-5.8.2-1.fc44.x86_64\ncontainers-common-0.67.0-1.fc44.noarch\n\/usr\/libexec\/podman\/quadlet<\/code><\/pre>\n\n\n
Quadlet uses two well-known directory paths. Rootful units live in \/etc\/containers\/systemd\/<\/code>; rootless units under the current user live in ~\/.config\/containers\/systemd\/<\/code>. The first one already exists on a default install (owned by the podman<\/code> package); the second you create on demand:<\/p>\n\n\n
ls -ld \/etc\/containers\/systemd\/\nmkdir -p ~\/.config\/containers\/systemd\/<\/code><\/pre>\n\n\n
The rootful directory is the one most setups start with; the rootless directory becomes important when you want containers tied to a user account rather than the host machine.<\/p>\n
Deploy a rootful container with a .container file<\/h2>\n
The minimal Quadlet unit type is .container<\/code>. It declares one container with its image, ports, and lifecycle. Create a unit file for an Nginx demo:<\/p>\n\n\n
sudo vi \/etc\/containers\/systemd\/web.container<\/code><\/pre>\n\n\n
Paste the following. Three sections matter: [Container]<\/code> is Quadlet-specific (image, ports, name, environment), [Service]<\/code> is standard systemd (restart policy, resource limits), and [Install]<\/code> determines what systemctl enable<\/code> hooks into:<\/p>\n\n\n
\"Quadlet<\/figure>\n\n\n
The plain-text version, same content:<\/p>\n\n\n
[Unit]\nDescription=Nginx demo container via Quadlet\nAfter=local-fs.target\n\n[Container]\nContainerName=web\nImage=docker.io\/library\/nginx:1.27-alpine\nPublishPort=8080:80\nAutoUpdate=registry\nEnvironment=NGINX_HOST=example.com\n\n[Service]\nRestart=always\n\n[Install]\nWantedBy=multi-user.target default.target<\/code><\/pre>\n\n\n
Reload systemd to trigger the Quadlet generator. It scans the well-known directory, sees the new file, and writes a translated .service<\/code> unit to \/run\/systemd\/generator\/<\/code>:<\/p>\n\n\n
sudo systemctl daemon-reload<\/code><\/pre>\n\n\n
Inspect what was generated. The output is annotated with the source file path so you can tell at a glance that this unit came from a Quadlet, not from a hand-written systemd file:<\/p>\n\n\n
sudo systemctl cat web.service | head -25<\/code><\/pre>\n\n\n
You will see something like the following. The SourcePath<\/code> directive points back at the original .container<\/code> file; the ExecStop<\/code> commands handle clean shutdown via podman rm<\/code>:<\/p>\n\n\n
\"systemctl<\/figure>\n\n\n
Start the unit. Pulling the Nginx image (about 20 MB) takes a few seconds the first time; subsequent starts use the cached image:<\/p>\n\n\n
sudo systemctl start web.service\nsudo systemctl status web.service --no-pager | head -10<\/code><\/pre>\n\n\n
The status line should read Active: active (running)<\/code>. Confirm the container is up via the Podman CLI and curl the published port to validate the network plumbing:<\/p>\n\n\n
sudo podman ps\ncurl -sI http:\/\/localhost:8080\/<\/code><\/pre>\n\n\n
Nginx responds HTTP\/1.1 200 OK<\/code>. The before-and-after sequence on a live F44 box:<\/p>\n\n\n
\"systemctl<\/figure>\n\n\n
The container is now a real systemd citizen: journalctl -u web.service<\/code> shows the container logs, systemctl enable web.service<\/code> would normally hook it into a target for boot, but Quadlet auto-handles this when WantedBy<\/code> is in the [Install]<\/code> section.<\/p>\n
Deploy a rootless container under your user<\/h2>\n
The rootless flow is the same, with three differences: the unit file lives in ~\/.config\/containers\/systemd\/<\/code>, you talk to systemd with systemctl --user<\/code>, and you need lingering enabled if you want the unit to survive logout:<\/p>\n\n\n
mkdir -p ~\/.config\/containers\/systemd ~\/caddy-data\nloginctl enable-linger $USER\nvi ~\/.config\/containers\/systemd\/api.container<\/code><\/pre>\n\n\n
The %h<\/code> token expands to the user’s home directory inside the Volume mapping (a Quadlet-specific convenience), and the :Z<\/code> suffix tells Podman to relabel the mount so SELinux lets the container write to it:<\/p>\n\n\n
[Unit]\nDescription=Caddy demo (rootless) via Quadlet\n\n[Container]\nContainerName=api\nImage=docker.io\/library\/caddy:2.10-alpine\nPublishPort=8081:80\nVolume=%h\/caddy-data:\/data:Z\n\n[Service]\nRestart=on-failure\n\n[Install]\nWantedBy=default.target<\/code><\/pre>\n\n\n
Reload the user systemd, start the unit, verify:<\/p>\n\n\n
systemctl --user daemon-reload\nsystemctl --user start api.service\nsystemctl --user status api.service --no-pager | head -10\npodman ps\ncurl -sI http:\/\/localhost:8081\/<\/code><\/pre>\n\n\n
Same drill: status reads active, podman ps<\/code> lists the container, and curl<\/code> returns 200. The crucial difference is the user namespace: the container’s UID 0 is your user’s UID on the host, so files the container writes to ~\/caddy-data<\/code> are owned by you, not root. The SELinux survival guide<\/a> covers what the :Z<\/code> mount option actually does at the policy layer.<\/p>\n
Compose containers with .network, .volume, and .pod<\/h2>\n
Real deployments need more than one container plus a shared volume and network. Quadlet supports four file types beyond .container<\/code>:<\/p>\n\n\n\n\n\n\n\n\n
File type<\/th>\nDefines<\/th>\nRefer to it in .container as<\/th>\n<\/tr>\n<\/thead>\n
.network<\/code><\/td>\nA user-defined Podman network<\/td>\nNetwork=mynet.network<\/code><\/td>\n<\/tr>\n
.volume<\/code><\/td>\nA named Podman volume<\/td>\nVolume=mydata.volume:\/data<\/code><\/td>\n<\/tr>\n
.pod<\/code><\/td>\nA Podman pod (multiple containers, shared netns)<\/td>\nPod=mypod.pod<\/code><\/td>\n<\/tr>\n
.build<\/code><\/td>\nAn image to build from a Containerfile\/Dockerfile<\/td>\nImage=myimage.build<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
A two-tier app (Postgres + a Node API) usually maps to one .network<\/code>, one .volume<\/code> (the database files), and two .container<\/code> files referencing them. Example database side:<\/p>\n\n\n
sudo vi \/etc\/containers\/systemd\/app-net.network<\/code><\/pre>\n\n\n
Network unit content:<\/p>\n\n\n
[Network]\nNetworkName=app-net\nDisableDNS=false\nDNS=1.1.1.1<\/code><\/pre>\n\n\n
Volume unit at \/etc\/containers\/systemd\/app-db-data.volume<\/code>:<\/p>\n\n\n
[Volume]\nVolumeName=app-db-data<\/code><\/pre>\n\n\n
Container unit at \/etc\/containers\/systemd\/app-db.container<\/code>, referencing the above by their unit names:<\/p>\n\n\n
[Container]\nContainerName=app-db\nImage=docker.io\/library\/postgres:17-alpine\nNetwork=app-net.network\nVolume=app-db-data.volume:\/var\/lib\/postgresql\/data:Z\nEnvironment=POSTGRES_PASSWORD=changeme\nEnvironment=POSTGRES_DB=app\n\n[Service]\nRestart=always\n\n[Install]\nWantedBy=multi-user.target<\/code><\/pre>\n\n\n
Reload and start; the generator brings the network and volume up first, then the container that depends on them:<\/p>\n\n\n
sudo systemctl daemon-reload\nsudo systemctl start app-db.service\nsudo podman ps\nsudo podman network ls\nsudo podman volume ls<\/code><\/pre>\n\n\n
The output of podman network ls<\/code> shows app-net<\/code> in the list, podman volume ls<\/code> shows app-db-data<\/code>, and the Postgres container reports listening on its standard port inside the network.<\/p>\n
Auto-update images with AutoUpdate=registry<\/h2>\n
One of Quadlet’s biggest selling points over hand-written systemd units is image auto-update. Add a single line to the [Container]<\/code> section, plus a system-wide systemd timer, and Podman pulls the new image on every check and restarts the container if a newer tag of the same digest exists:<\/p>\n\n\n
AutoUpdate=registry<\/code><\/pre>\n\n\n
Enable the auto-update timer for the host. It runs once per day by default; check current state with:<\/p>\n\n\n
sudo systemctl enable --now podman-auto-update.timer\nsudo systemctl list-timers podman-auto-update --no-pager<\/code><\/pre>\n\n\n
Force an immediate check (useful when validating the workflow) with sudo podman auto-update<\/code>. The command reports which containers were checked, whether a new image was pulled, and whether the unit was restarted. Containers without AutoUpdate=registry<\/code> in their Quadlet definition are silently skipped, which is exactly the opt-in behavior you want.<\/p>\n
Convert existing docker-compose files<\/h2>\n
For teams migrating from Docker Compose or Kubernetes manifests, the cleanest path is one .container<\/code> file per service. There is no auto-conversion tool that handles the full Compose feature set; the manual mapping is straightforward enough:<\/p>\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Compose key<\/th>\nQuadlet equivalent<\/th>\n<\/tr>\n<\/thead>\n
image<\/code><\/td>\nImage=<\/code> in [Container]<\/code><\/td>\n<\/tr>\n
ports<\/code><\/td>\nPublishPort=8080:80<\/code><\/td>\n<\/tr>\n
volumes<\/code><\/td>\nVolume=path-or-volume.volume:\/in\/container:Z<\/code><\/td>\n<\/tr>\n
environment<\/code><\/td>\nEnvironment=KEY=value<\/code> (one per line)<\/td>\n<\/tr>\n
env_file<\/code><\/td>\nEnvironmentFile=\/path\/to\/file<\/code><\/td>\n<\/tr>\n
depends_on<\/code><\/td>\n[Unit] After=other.service<\/code><\/td>\n<\/tr>\n
restart: always<\/code><\/td>\n[Service] Restart=always<\/code><\/td>\n<\/tr>\n
networks<\/code><\/td>\nNetwork=mynet.network<\/code> + matching .network<\/code> file<\/td>\n<\/tr>\n
healthcheck<\/code><\/td>\nHealthCmd=<\/code>, HealthInterval=<\/code>, HealthRetries=<\/code><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n
For the few Compose features without a clean mapping (build dependencies across services, profiles, the extends<\/code> keyword), use podman-compose<\/code> as a stop-gap and migrate one service at a time as you touch it.<\/p>\n
Troubleshoot common Quadlet errors<\/h2>\n
Error: “Unit web.service not found” after daemon-reload<\/h3>\n
The Quadlet generator did not pick up your file. Most common causes: the file is not under one of the watched directories (\/etc\/containers\/systemd\/<\/code>, \/usr\/share\/containers\/systemd\/<\/code>, or ~\/.config\/containers\/systemd\/<\/code> for rootless), or the filename is missing the .container<\/code> extension. Verify with:<\/p>\n\n\n
sudo \/usr\/libexec\/podman\/quadlet -dryrun \/etc\/containers\/systemd\/ 2>&1 | head -20<\/code><\/pre>\n\n\n
Dry-run mode prints what would be generated for each file, plus any parse errors. Fix the warnings before re-running daemon-reload<\/code>.<\/p>\n
Error: “ContainerName ‘web’ is already in use”<\/h3>\n
A previous run of the same container left a dangling container with the same name. The Quadlet-generated ExecStopPost<\/code> tries to clean this up, but a SIGKILL or sudden host reboot can leave one behind. Remove it manually:<\/p>\n\n\n
sudo podman rm -f web\nsudo systemctl start web.service<\/code><\/pre>\n\n\n
Once the dangling container is gone, the unit starts cleanly and Podman recreates the container with the desired name.<\/p>\n
Error: rootless container fails to write to a host-mounted volume<\/h3>\n
SELinux is blocking the write because the volume is not labelled container_file_t<\/code>. Add the :Z<\/code> mount option (or :z<\/code> for shared, when multiple containers need access). If you cannot edit the volume line, label the path manually:<\/p>\n\n\n
sudo semanage fcontext -a -t container_file_t \"\/path\/to\/data(\/.*)?\"\nsudo restorecon -Rv \/path\/to\/data<\/code><\/pre>\n\n\n
Restart the container after relabelling and the writes succeed; the label change is persistent across reboots.<\/p>\n
Error: rootless unit stops when you log out<\/h3>\n
Lingering is not enabled for your user, so systemd kills the user manager when you log out. Enable lingering (once, persistent) with loginctl enable-linger $USER<\/code>; check the status with loginctl show-user $USER | grep Linger<\/code>.<\/p>\n
Error: image pull fails with “no such host” or DNS errors<\/h3>\n
The container is starting before the network is up. The Quadlet generator adds Wants=network-online.target<\/code> automatically, but very fast-booting hosts can still race. Add an explicit retry in the [Service]<\/code> section:<\/p>\n\n\n
[Service]\nRestart=on-failure\nRestartSec=10s<\/code><\/pre>\n\n\n
The image pull happens once on first start, then the cached image is used; transient DNS failures recover on the next restart attempt.<\/p>\n
With Quadlet, the line between “a container running” and “a service running” disappears. The integration with systemd is real, the rootless path actually works, and the auto-update behavior makes long-running deployments much less of a babysit. Pair this with the Distrobox and Toolbox guide<\/a> for interactive container dev environments, the Podman Compose setup<\/a> for the migration path from docker-compose.yml<\/code>, and the firewalld walkthrough<\/a> for the host-side network policy that should sit in front of the published ports.<\/p>","protected":false},"excerpt":{"rendered":"
If you have ever run a container long-term with podman run -d, you have written a deployment with no lifecycle, no logging integration, and no obvious way to restart on host reboot. Quadlet is Podman’s answer to that gap: drop a small declarative file in the right systemd directory, run systemctl daemon-reload, and Podman generates … Read more<\/a><\/p>\n","protected":false},"author":28,"featured_media":167947,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[316,29,299,47,50],"tags":[681,282],"cfg_series":[39847],"class_list":["post-167951","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-containers","category-fedora","category-how-to","category-linux","category-linux-tutorials","tag-fedora","tag-linux","cfg_series-fedora-44-workstation"],"_links":{"self":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/167951","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/users\/28"}],"replies":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/comments?post=167951"}],"version-history":[{"count":2,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/167951\/revisions"}],"predecessor-version":[{"id":167974,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/posts\/167951\/revisions\/167974"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media\/167947"}],"wp:attachment":[{"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/media?parent=167951"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/categories?post=167951"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/tags?post=167951"},{"taxonomy":"cfg_series","embeddable":true,"href":"https:\/\/computingforgeeks.com\/wp-json\/wp\/v2\/cfg_series?post=167951"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}