Skip to content

docs: improve note about Quadlet TimeoutStartSec #27584

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Nov 24, 2025
Merged

docs: improve note about Quadlet TimeoutStartSec #27584

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
d1c2afc
docs: improve note about Quadlet TimeoutStartSec
salim-b Nov 21, 2025
7b30d9c
docs: further tweaks
salim-b Nov 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 8 additions & 9 deletions docs/source/markdown/podman-systemd.unit.5.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,14 +85,13 @@ or [DynamicUser](https://www.freedesktop.org/software/systemd/man/latest/systemd
systemd options. If you want to run a rootless Quadlet, you will need to create the user
and add the unit file to one of the above rootless unit search paths.

Note: When a Quadlet is starting, Podman often pulls or builds one more container images which may take a considerable amount of time.
Systemd defaults service start time to 90 seconds, or fails the service. Pre-pulling the image or extending
the systemd timeout time for the service using the *TimeoutStartSec* Service option can fix the problem.
A word of caution: *TimeoutStartSec* is not available for `Type=oneshot` units. Refer to `systemd.service(5)`
for more information on how to handle long startup times for units which do not need to stay active
once their main process has finished.
When a Quadlet unit starts, Podman may need to pull or build container images, which can take significantly longer
than systemd's default 90-second service startup limit. If this causes the unit to fail, you can either pre-pull the
required images or increase the service's startup timeout using the *TimeoutStartSec* option. Keep in mind, however,
that *TimeoutStartSec* cannot be used with units that specify `Type=oneshot` (their startup timeout is disabled by
default). For further details on *TimeoutStartSec*, see `systemd.service(5)`.

Adding the following snippet to a Quadlet file extends the systemd timeout to 15 minutes.
Adding the following snippet to a Quadlet file extends the startup timeout to 15 minutes.

```
[Service]
Expand Down Expand Up @@ -2373,7 +2372,7 @@ Image=quay.io/example/my-app:latest
Mount=type=artifact,source=my-artifact.artifact,destination=/etc/config
```

Example for Container in a Pod:
Example for a container in a Pod:

`test.pod`
```
Expand All @@ -2389,7 +2388,7 @@ Exec=sh -c "sleep inf"
Pod=test.pod
```

Example for a Pod with a oneshot Startup Task:
Example for a Pod with a one-shot startup task:

`test.pod`
```
Expand Down