How to Run Podman Quadlets on Raspberry Pi

#podman #raspberrypi #tutorial #debian

I'm trying to create a small set of articles related to podman, so I thought about starting from the start; how to get it running in my Raspberry Pi, which is using Debian 13 (trixie)

1. Install Podman
2. Prepare the User Environment
3. Create the Quadlet Directory
4. Create a Sample Quadlet
5. Activate and Start the Service
6. Enable Service at boot

1. Install Podman

First, update your package list and install Podman.

[|=| raspi in ~ ]$ sudo apt update && sudo apt install -y podman
Get:1 http://security.debian.org/debian-security trixie-security InRelease [43.4 kB]
Get:2 http://archive.raspberrypi.org/debian trixie InRelease [54.8 kB]
[...]
Installing:
  podman

Suggested packages:
  docker-compose

Summary:
  Upgrading: 0, Installing: 1, Removing: 0, Not Upgrading: 4
  Download size: 21.2 MB
  Space needed: 82.6 MB / 195 GB available

Get:1 http://deb.debian.org/debian trixie/main arm64 podman arm64 5.4.2+ds1-2+b2 [21.2 MB]
Fetched 21.2 MB in 1s (16.7 MB/s)
Selecting previously unselected package podman.
(Reading database ... 76622 files and directories currently installed.)
Preparing to unpack .../podman_5.4.2+ds1-2+b2_arm64.deb ...
Unpacking podman (5.4.2+ds1-2+b2) ...
Setting up podman (5.4.2+ds1-2+b2) ...
Processing triggers for man-db (2.13.1-1) ...

[|=| raspi in ~ ]$

2. Prepare the User Environment

For a local user to run services that start at boot (without being logged in), you must enable lingering. This allows the user's systemd instance to start on boot and stay running after logout.

[|=| raspi in ~ ]$ sudo loginctl enable-linger $USER

[|=| raspi in ~ ]$

3. Create the Quadlet Directory

Quadlets for local users are stored in a specific directory within your home folder. Systemd will look here to generate the service files.

[|=| raspi in ~ ]$ mkdir -p ~/.config/containers/systemd

[|=| raspi in ~ ]$

4. Create a Sample Quadlet

To test the setup, create a simple container Quadlet file (e.g., a basic Nginx server).

[|=| raspi in ~ ]$ cat ~/.config/containers/systemd/hello.container
[Unit]
Description=A simple Quadlet container

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=4242:80

[|=| raspi in ~ ]$

5. Activate and Start the Service

Because Quadlets use a systemd generator, you must reload the user-level daemon to "see" the new file and generate the underlying .service file.

# Reload the user's systemd daemon
[|=| raspi in ~ ]$ systemctl --user daemon-reload

[|=| raspi in ~ ]$
# Start and confirm the generated service status

[|=| raspi in ~ ]$ systemctl --user start hello.service

[|=| raspi in ~ ]$ systemctl --user status hello.service
● hello.service - A simple Quadlet container
     Loaded: loaded (/home/solifugo/.config/containers/systemd/hello.container; generated)
     Active: active (running) since Mon 2026-02-16 13:31:49 GMT; 7s ago
[...]
[|=| raspi in ~ ]$

[|=| raspi in ~ ]$ curl 127.0.0.1:4242
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
<style>
html { color-scheme: light dark; }
body { width: 35em; margin: 0 auto;
font-family: Tahoma, Verdana, Arial, sans-serif; }
</style>
</head>
<body>
<h1>Welcome to nginx!</h1>
<p>If you see this page, the nginx web server is successfully installed and
working. Further configuration is required.</p>

<p>For online documentation and support please refer to
<a href="http://nginx.org/">nginx.org</a>.<br/>
Commercial support is available at
<a href="http://nginx.com/">nginx.com</a>.</p>

<p><em>Thank you for using nginx.</em></p>
</body>
</html>

[|=| raspi in ~ ]$

6. Enable Service at boot

The enable command is used to enable a systemd service to start automatically on boot, however, for podman we can do it by including an [Install] section inside the .container file.

[|=| raspi in ~ ]$ cat ~/.config/containers/systemd/hello.container
[Unit]
Description=A simple Quadlet container

[Container]
Image=docker.io/library/nginx:alpine
PublishPort=4242:80

[Install]
# This is the "enable" equivalent for Quadlets
WantedBy=default.target

[|=| raspi in ~ ]$

After changing the service file, we always need to reload the user-level daemon

We can confirm now that we are having a service symbolic link of the right folder so it will start automatically when booting into the default target

[|=| raspi in ~ ]$ ls -l /run/user/$(id -u)/systemd/generator/default.target.wants/hello.service
ls: cannot access '/run/user/1001/systemd/generator/default.target.wants/hello.service': No such file or directory

[|=| raspi in ~ ]$ systemctl --user daemon-reload

[|=| raspi in ~ ]$ ls -l /run/user/$(id -u)/systemd/generator/default.target.wants/hello.service
lrwxrwxrwx 1 solifugo solifugo 16 Feb 16 13:49 /run/user/1001/systemd/generator/default.target.wants/hello.service -> ../hello.service

[|=| raspi in ~ ]$