podman-quadlet-basic-usage(7) Miscellaneous Information Manual podman-quadlet-basic-usage(7)

# [NAME](#NAME)

podman-quadlet-basic-usage - Basic usage examples and step-by-step guide for Podman Quadlet

# [DESCRIPTION](#DESCRIPTION)

This guide introduces common usage patterns for Podman Quadlet. It provides step-by-step examples for defining containers, exposing ports, creating volumes, and establishing dependencies using declarative **.container**, **.volume**, and related unit files.

Quadlet simplifies container lifecycle management by translating these files into systemd services, making them manageable with **systemctl**.

# [EXAMPLE 1: RUNNING A SIMPLE CONTAINER](#EXAMPLE_1:_RUNNING_A_SIMPLE_CONTAINER)

# Step 1: Create **hello.container**

```
[Unit]
Description=Hello Alpine Container
[Container]
Image=alpine
Exec=echo Hello from Quadlet!
[Install]
WantedBy=multi-user.target
```

# [Step 2: Place the file](#Step_2:_Place_the_file)

For rootless use:

```
mkdir -p ~/.config/containers/systemd
cp hello.container ~/.config/containers/systemd/
```

For rootful use:

```
sudo cp hello.container /etc/containers/systemd/
```

# [Step 3: Reload and start the service](#Step_3:_Reload_and_start_the_service)

For rootless use:

```
systemctl --user daemon-reload
systemctl --user start hello.service
```

For rootful use:

```
sudo systemctl daemon-reload
sudo systemctl start hello.service
```

Note quadlet services cannot be enabled as they are a generated systemd unit, see [podman-systemd.unit(5)](/man/enterprise-packages/podman-doc-6.0/podman-systemd.unit.5) for more information.

# [Expected Output:](#Expected_Output:)

For rootless, check logs using:

```
journalctl --user -u hello.service
```

For rootful:

```
journalctl -u hello.service
```

You should see: **Hello from Quadlet!**

That means the container started, executed the echo command, and exited.

# [EXAMPLE 2: CREATING A NAMED VOLUME](#EXAMPLE_2:_CREATING_A_NAMED_VOLUME)

# Step 1: Create **mydata.volume**

```
[Volume]
VolumeName=mydata
Label=purpose=demo
```

# [Step 2: Place and reload](#Step_2:_Place_and_reload)

For rootless use:

```
mkdir -p ~/.config/containers/systemd
cp mydata.volume ~/.config/containers/systemd/
systemctl --user daemon-reload
```

For rootful use:

```
sudo cp mydata.volume /etc/containers/systemd/
sudo systemctl daemon-reload
```

# [Step 3: Create the volume](#Step_3:_Create_the_volume)

For rootless use:

```
systemctl --user start mydata-volume.service
```

For rootful use:

```
systemctl start mydata-volume.service
```

# [EXAMPLE 3: CONTAINER USING A VOLUME](#EXAMPLE_3:_CONTAINER_USING_A_VOLUME)

# Create **with-volume.container**

```
[Unit]
Description=Container with Mounted Volume
[Container]
Image=alpine
Exec=sh -c "ls /data && echo Hello > /data/hello.txt"
Volume=mydata.volume:/data
[Install]
WantedBy=multi-user.target
```

This container lists all files in the volume and creates **hello.txt**.

# [Start the container and check the status](#Start_the_container_and_check_the_status)

For rootless use:

```
cp with-volume.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start with-volume.service
systemctl --user status with-volume.service
```

For rootful use:

```
sudo cp with-volume.container /etc/containers/systemd/
sudo systemctl daemon-reload
sudo systemctl start with-volume.service
sudo systemctl status with-volume.service
```

When started for the first time, the **hello.txt** will not appear in the **systemctl status** output, because it has not been created yet. But when started for the second time, the output will be:

```
hello.txt
```

This means the volume is used and is persistent.

# [EXAMPLE 4: EXPOSING A CONTAINER PORT TO THE HOST](#EXAMPLE_4:_EXPOSING_A_CONTAINER_PORT_TO_THE_HOST)

# Create **webserver.container**

```
[Unit]
Description=Nginx Webserver
[Container]
Image=nginx:alpine
PublishPort=8080:80
[Install]
WantedBy=multi-user.target
```

# [Start the web server](#Start_the_web_server)

For rootless use:

```
cp webserver.container ~/.config/containers/systemd/
systemctl --user daemon-reload
systemctl --user start webserver.service
```

For rootful use:

```
sudo cp webserver.container /etc/containers/systemd/
sudo systemctl daemon-reload
sudo systemctl start webserver.service
```

Visit **http://localhost:8080** in your browser.

# [TIPS](#TIPS)

To start a container on system boot, use:

```
[Install]
WantedBy=multi-user.target
```

If **systemctl** cannot find **foo.service**, it usually means there is a syntax error in your Quadlet file. To find the details, use:

```
systemd-analyze --user --generators=true verify foo.service
```

# [SEE ALSO](#SEE_ALSO)

[podman-systemd.unit(5)](/man/enterprise-packages/podman-doc-6.0/podman-systemd.unit.5), [podman-container.unit(5)](/man/enterprise-packages/podman-doc-6.0/podman-container.unit.5), [podman-volume.unit(5)](/man/enterprise-packages/podman-doc-6.0/podman-volume.unit.5), [systemd.unit(5)](/man/enterprise-packages/podman-doc-6.0/systemd.unit.5)

# [AUTHORS](#AUTHORS)

Podman Team ⟨https://podman.io⟩

---

Document: podman-quadlet-basic-usage(7) from podman-doc-6.0 6.0.2-r12 (Chainguard OS)
Source: https://github.com/containers/podman