podman/docs/source/markdown/podman-systemd.unit.5.md

% podman-systemd.unit(5)

NAME

podman-systemd.unit - High-level overview of Podman Quadlet integration with systemd

DESCRIPTION

Quadlet is a systemd unit generator that enables declarative container management by defining Podman resources using specialized systemd unit files. It provides an interface between Podman and systemd, allowing users to manage containers, pods, volumes, images, and more through native systemd service units.

Quadlet parses .container, .pod, .volume, .network, .image, .build, and .kube files located in well-known directories and converts them into corresponding .service units for systemd. These units are then used to create and manage container resources on boot or via explicit systemctl commands.

PURPOSE

Quadlet's goal is to bridge the gap between container lifecycle management and system initialization. It lets you define container infrastructure declaratively, leveraging systemd's features such as dependency ordering, restart policies, boot-time activation, logging, and drop-in configuration.

It eliminates the need to write complex ExecStart= lines or manage custom systemd services manually.

BENEFITS

• Declarative and human-readable unit definitions
• Seamless integration with native systemd features
• Consistent naming and dependency management
• Support for advanced Podman features (pods, kube, image builds)
• Rootless and rootful compatibility
• Drop-in override support for all unit types

INTEGRATION WITH SYSTEMD

At boot time, the podman-system-generator reads Quadlet unit files from predefined directories and translates them into .service files under /run/systemd/generator/. These generated services are treated like native systemd units and can be enabled, started, and inspected using standard tools such as:

systemctl enable my-container.service
systemctl start my-container.service
journalctl -u my-container.service

Quadlet integrates cleanly with both rootless and rootful Podman environments, depending on the search paths used.

FILE TYPES

Quadlet supports the following file types:

• .container — Defines and manages a single container. See podman-container.unit(5).
• .pod — Creates a Podman pod that containers can join. See podman-pod.unit(5).
• .volume — Ensures a named Podman volume exists. See podman-volume.unit(5).
• .network — Creates a Podman network for containers and pods. See podman-network.unit(5).
• .image — Pulls and caches a container image. See podman-image.unit(5).
• .build — Builds a container image from a Containerfile. See podman-build.unit(5).
• .kube — Deploys containers from Kubernetes YAML using podman-kube.unit(5).

Each file is mapped to a corresponding .service unit with a predictable naming pattern, typically appending -<type>.service to the unit base name.

FILE PATHS

Quadlet files should be stored in specific directories depending on rootless or rootful execution.

Rootful

• /run/containers/systemd/
• /etc/containers/systemd/
• /usr/share/containers/systemd/

Rootless

• $XDG_RUNTIME_DIR/containers/systemd/
• $XDG_CONFIG_HOME/containers/systemd/ or ~/.config/containers/systemd/
• /etc/containers/systemd/users/$(UID)
• /etc/containers/systemd/users/

QUADLET SECTION [Quadlet]

Some quadlet specific configuration is shared between different unit types. Those settings can be configured in the [Quadlet] section.

Valid options for [Quadlet] are listed below:

[Quadlet] options	Description
DefaultDependencies=false	Disable implicit network dependencies to the unit

DefaultDependencies=

Add Quadlet's default network dependencies to the unit (default is true).

When set to false, Quadlet will not add a dependency (After=, Wants=) to network-online.target/podman-user-wait-network-online.service to the generated unit.

Note, this option is set in the [Quadlet] section. The systemd [Unit] section has an option with the same name but a different meaning.

SEE ALSO

podman-container.unit(5), podman-pod.unit(5), podman-volume.unit(5), podman-network.unit(5), podman-image.unit(5), podman-build.unit(5), podman-kube.unit(5), systemd.unit(5)

AUTHORS

Podman Team https://podman.io