Skip to content
Tutorials Center
My learning

Topics

Lesson 24 of 37 ยท Compose and Quadlet

Quadlet: Containers as systemd Units

Run containers as systemd services with Quadlet: where to put .container files, the Container, Service and Install sections, reload and start commands, rootless setup and debugging.

On a server you usually want a container to start at boot, restart if it crashes, log to the journal and be stopped cleanly on shutdown. systemd already does all of that for services. Quadlet lets you describe a container in a small declarative file, and systemd turns it into a real service for you. It is now the recommended way to run long-lived Podman containers, replacing the older podman generate systemd command.

This lesson covers the .container file format, where files live, how to start them and how to debug problems. Quadlet needs systemd, so the commands are read-only here. The runnable examples are stand-ins that generate and check unit files.

How Quadlet works

You write name.container. A systemd generator (a program that runs whenever systemd reloads) reads it and writes a normal name.service into a temporary directory. That service runs podman run with the right options. You never edit the generated service.

Quadlet pipeline

.container file You describe the container.
Generator Runs at daemon-reload.
.service A real systemd unit.
podman run Starts and supervises it.

Edit the .container file, not the service.

1 / 2

Where files go

Mode Directory
Rootful, admin-managed /etc/containers/systemd/
Rootful, shipped by packages /usr/share/containers/systemd/
Rootless, one user ~/.config/containers/systemd/
Rootless, all users /etc/containers/systemd/users/

Subdirectories are scanned too, so you can organize files per project.

Your first .container file

Create ~/.config/containers/systemd/web.container:

INI
[Unit]
Description=Static web server

[Container]
Image=docker.io/library/nginx:stable
PublishPort=127.0.0.1:8080:80
Volume=%h/site:/usr/share/nginx/html:ro,Z

[Service]
Restart=always

[Install]
WantedBy=default.target

Then, as that user:

Terminal
systemctl --user daemon-reload
systemctl --user start web.service
systemctl --user status web.service
journalctl --user -u web.service -f

The generated service name is the file name with .service. There is no systemctl enable for Quadlet units: the [Install] section is read by the generator, so a WantedBy= line makes the service start automatically. For a rootless service to start at boot without you logging in, enable lingering once:

Terminal
loginctl enable-linger $USER

%h is systemd's specifier for the user's home directory; %t is the runtime directory.

The three sections

[Unit] and [Service] and [Install] are ordinary systemd sections. Use [Unit] for Description=, After=network-online.target and Wants=, and [Service] for Restart=, TimeoutStartSec= (give big image pulls time) and Environment=.

[Container] is the Quadlet-specific section. Frequently used keys:

Key Same as Notes
Image= image argument Required (or Rootfs=)
ContainerName= --name Defaults to systemd-<unit name>
PublishPort= -p Repeat the key for several ports
Environment= -e Environment=KEY=value
EnvironmentFile= --env-file File with KEY=value lines
Volume= -v Host path, named volume, or a .volume file
Network= --network Name or a .network file
Exec= command Arguments after the image
User= / Group= --user Run as another user inside
AutoUpdate= label registry enables podman auto-update
PodmanArgs= any flag Escape hatch for options without a key
HealthCmd= --health-cmd Health check command

Keys that can appear more than once (like PublishPort= and Volume=) are repeated on separate lines.

Generating a unit file

A small generator makes the structure concrete. This stand-in turns a Python dictionary into a .container text, repeating list-valued keys the way Quadlet expects.

Python Build a .container file (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Checking a unit before you start it

Syntax mistakes show up only when the generator runs. You can run the generator by hand in dry-run mode and read its output (the exact path of the generator differs between distributions):

Terminal
/usr/lib/systemd/system-generators/podman-system-generator --user --dryrun

Recent Podman versions also have podman quadlet subcommands for installing and listing units. When a service refuses to appear after daemon-reload, check journalctl --user -b | grep -i quadlet for the generator's complaint.

This stand-in does a small version of that check: it reports missing Image=, unknown sections and lines outside a section.

Python Lint a .container file (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Day-to-day operation

Terminal
systemctl --user restart web.service     # picks up changes after daemon-reload
systemctl --user stop web.service
podman ps                               # the container is named systemd-web
journalctl --user -u web.service        # logs

After editing a .container file, always run systemctl --user daemon-reload before restarting; otherwise systemd keeps running the old definition.

Do not use podman run --restart=always for services you also manage with Quadlet. Let systemd own restarts through Restart=, so there is only one supervisor.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does a rootless user put a .container file?

    ~/.config/containers/systemd/ is scanned for rootless Quadlet files.
  2. 2. What must you run after editing a .container file?

    daemon-reload makes the generator rebuild the .service from your file.
  3. 3. How do you give a container two published ports in a .container file?

    Multi-valued keys are repeated, one value per line.
  4. 4. What makes a rootless Quadlet service start at boot without a login session?

    Lingering keeps the user's systemd instance running, so WantedBy=default.target services start at boot.

Summary

  • Quadlet turns name.container files into name.service units through a systemd generator.
  • Rootless files live in ~/.config/containers/systemd/; rootful ones in /etc/containers/systemd/.
  • The [Container] section holds Podman options (Image=, PublishPort=, Volume=, Environment=, ...); [Service] and [Install] are normal systemd.
  • Run daemon-reload after every edit; use lingering for rootless services at boot.
  • Let systemd supervise restarts instead of Podman's --restart.

Next: Quadlet for Pods, Volumes and Networks