tmpfiles.d is a declarative way to say “this path must exist, with this owner and mode, and old files inside it must be removed”. The configs are applied by systemd-tmpfiles at boot and on a timer.

Typical uses:

  • create directories in /run (tmpfs, empty after every reboot)
  • clean up /tmp, /var/tmp, caches, and old logs by age
  • fix owner and permissions on existing paths
  • create symlinks, copy default configs
  • write values to /sys and /proc at boot

Contents#

  1. Where configs live
  2. Line format
  3. Types
  4. Modifiers
  5. Mode, owner, age
  6. Specifiers
  7. When it runs
  8. Commands
  9. Examples
  10. User tmpfiles
  11. tmpfiles.d vs unit directives
  12. Gotchas

1. Where configs live#

Directory Who writes it
/etc/tmpfiles.d/ admin, highest priority
/run/tmpfiles.d/ runtime generated
/usr/local/lib/tmpfiles.d/ locally installed software
/usr/lib/tmpfiles.d/ distribution packages

Rules:

  • Files must end in .conf.
  • A file in /etc/tmpfiles.d/ with the same name as one in /usr/lib/tmpfiles.d/ replaces it completely.
  • To disable a vendor file, symlink it to /dev/null:
ln -s /dev/null /etc/tmpfiles.d/tmp.conf
  • All files from all directories are sorted by file name and processed in that order, regardless of the directory.
  • If two files contain a line for the same path, the line from the file whose name sorts first wins. That is why local overrides often get names like 00-local.conf.

See the final merged config:

systemd-tmpfiles --cat-config

2. Line format#

#Type  Path                Mode  User   Group  Age  Argument
d      /run/myapp          0750  myapp  myapp  -    -
  • Fields are separated by whitespace. Lines starting with # are comments.
  • - means “default” or “not used”.
  • Trailing fields can be omitted.
  • A path with spaces must be quoted. C-style escapes like \x20 also work.
  • Most types accept glob patterns in the path (r, R, w, z, Z, x, X, e and others).

3. Types#

Create things:

Type What it does
f Create a file if it does not exist. If Argument is set, write it into the file only on creation
f+ Create a file or truncate an existing one, then write Argument
w Write Argument into an existing file. Does not create it. Typical for /sys and /proc
w+ Same as w, but append
d Create a directory. If it exists, fix mode and owner. Contents are cleaned by Age
D Like d, but the contents are removed on --remove (at boot)
e Like d, but only for an existing directory, never creates it. Useful for cleanup only
v Create a btrfs subvolume, a plain directory on other filesystems
q, Q Like v, plus btrfs quota group settings
p, p+ Create a named pipe (FIFO). + replaces whatever exists at the path
L, L+ Create a symlink to Argument. L+ replaces an existing file or symlink
c, c+ Create a character device node
b, b+ Create a block device node
C, C+ Copy a file or directory tree from Argument, only if the target does not exist (or is an empty directory). C+ copies recursively into an existing directory, skipping files that already exist. If Argument is omitted, the source is /usr/share/factory/<path>

Remove things:

Type What it does
r Remove a file or an empty directory
R Remove recursively

Exclude from cleanup:

Type What it does
x Do not clean this path and its contents
X Do not clean this path itself, but its contents can still be cleaned

Fix attributes of existing paths:

Type What it does
z Set mode, owner, SELinux label. Not recursive
Z Same, recursively
t, T Set extended attributes (xattr). T is recursive
h, H Set file attributes like chattr (+C, +i, …). H is recursive
a, a+ Set POSIX ACL. a+ adds to the existing ACL instead of replacing it
A, A+ Same, recursively

4. Modifiers#

Modifiers are appended to the type letter, for example d!, L+, w-.

Modifier Meaning
! Apply the line only at boot (--boot). Safe for things that must not run again on a live system
- Ignore errors when creating the path
= If the path exists but has the wrong type (a file instead of a directory, for example), remove it first
~ Argument is base64-encoded
^ Argument is the name of a systemd credential, its value is used as content
+ Type-specific: replace, overwrite, append. See the tables above

5. Mode, owner, age#

Mode

  • - uses the default: 0644 for files, 0755 for directories.
  • ~0750: mask by the existing mode. If the path has no execute bits, they are not added (same for read and write). Useful with Z to avoid making all files executable.
  • :0640: apply the mode only when the path is created. An existing path keeps its mode.

User / Group

  • A name or a numeric ID. - means root (or the current user in --user mode).
  • A : prefix (:myapp) means the same as for mode: set only on creation.
  • The user must exist when the line is applied. For service users, create them with sysusers.d first. At boot systemd-sysusers runs before systemd-tmpfiles.

Age

How old a file must be to be removed during cleanup. - means “never clean”.

10s  30min  12h  7d  4w

By default the newest of atime, mtime, ctime (and btime) is compared with the age. This can be narrowed with a prefix before ::

Letter Timestamp Applies to
a / A access files / directories
b / B birth files / directories
c / C change files / directories
m / M modify files / directories
# Remove files that have not been modified for 7 days, ignore atime
d /var/cache/myapp 0755 myapp myapp mM:7d

A ~ before the age (~7d) cleans only the second level and below. Files and directories directly inside the path are kept.

Cleanup also skips:

  • files and directories that are excluded with x / X
  • directories that are locked with flock(LOCK_EX) or flock(LOCK_SH). An application can lock its directory in /tmp so nothing is deleted while it runs
  • mount points

6. Specifiers#

Lines can contain % specifiers. Most useful:

Specifier Value
%h user home directory
%u / %U user name / UID
%g / %G group name / GID
%t runtime directory: /run or $XDG_RUNTIME_DIR
%S state directory: /var/lib or ~/.local/state
%C cache directory: /var/cache or ~/.cache
%L logs directory: /var/log or ~/.local/state/log
%T /tmp
%V /var/tmp
%H hostname
%m machine ID
%b boot ID
%% a literal %

%h, %t, %S, %C are most useful in user mode, see User tmpfiles.


7. When it runs#

Unit When What
systemd-tmpfiles-setup-dev-early.service, systemd-tmpfiles-setup-dev.service early boot only device nodes and /dev related lines
systemd-tmpfiles-setup.service boot --create --remove --boot
systemd-tmpfiles-clean.timer 15 min after boot, then daily --clean

Change the cleanup schedule:

systemctl edit systemd-tmpfiles-clean.timer
[Timer]
OnUnitActiveSec=
OnUnitActiveSec=6h

Package managers also apply a new config right after install: Arch has a pacman hook, RPM-based distributions use the %tmpfiles_create macro, Debian uses a dh_installtmpfiles snippet.


8. Commands#

# Apply create lines from all configs
systemd-tmpfiles --create

# Apply only one file (name or full path)
systemd-tmpfiles --create myapp.conf
systemd-tmpfiles --create /etc/tmpfiles.d/myapp.conf

# Run cleanup by age
systemd-tmpfiles --clean

# Remove paths marked with r, R, D
systemd-tmpfiles --remove

# Only for paths under a prefix
systemd-tmpfiles --create --prefix=/run/myapp

# Show what would happen, change nothing (systemd 256+)
systemd-tmpfiles --dry-run --clean

# Merged config
systemd-tmpfiles --cat-config

# Short syntax reference (systemd 255+)
systemd-tmpfiles --tldr

Debugging:

SYSTEMD_LOG_LEVEL=debug systemd-tmpfiles --clean
journalctl -u systemd-tmpfiles-setup.service -u systemd-tmpfiles-clean.service

Lines with ! are applied only together with --boot. If a manual --create “does nothing”, check for !.


9. Examples#

Runtime directory for a daemon (/run is empty after reboot)

# /etc/tmpfiles.d/myapp.conf
d /run/myapp 0750 myapp myapp -

Cache with cleanup by age

d /var/cache/myapp 0750 myapp myapp 14d

Clean an existing directory, do not create it

e /srv/uploads/tmp - - - 2d

Keep some files in /tmp from cleanup

x /tmp/build-cache-*
X /tmp/shared

Change /tmp cleanup age

Find the vendor file first:

systemd-tmpfiles --cat-config | grep -E '^[^#].* /tmp( |$)'

Then override it with a file of the same name in /etc/tmpfiles.d/ (usually tmp.conf):

# /etc/tmpfiles.d/tmp.conf
q /tmp     1777 root root 3d
q /var/tmp 1777 root root 30d

Remember that a file with the same name replaces the whole vendor file. Copy all lines you want to keep.

Kernel settings in /sys at boot

# /etc/tmpfiles.d/thp.conf
w- /sys/kernel/mm/transparent_hugepage/enabled - - - - madvise
w- /sys/kernel/mm/transparent_hugepage/defrag  - - - - defer+madvise

- ignores the error on hosts where the file does not exist. For /proc/sys values prefer sysctl.d.

Fix owner and permissions of logs

Z /var/log/myapp ~0750 myapp adm -

With ~ files without execute bits get 0640, directories get 0750.

Symlink

L+ /etc/myapp/config.toml - - - - /srv/config/myapp.toml

Default config, copied only once

C /etc/myapp/config.toml - - - - /usr/share/myapp/config.toml.example

File with initial content

f /var/lib/myapp/settings.ini 0640 myapp myapp - mode=default

The content is written only on creation. Edits made later are not overwritten.

Remove leftovers at boot

r! /var/lib/myapp/*.pid
R! /var/tmp/myapp-*

Disable copy-on-write for database files on btrfs

d /var/lib/postgres/data 0700 postgres postgres -
h /var/lib/postgres/data - - - - +C

+C only affects files created after the attribute is set.


10. User tmpfiles#

The same mechanism works per user with --user. Directories:

Directory Scope
~/.config/user-tmpfiles.d/ this user
~/.local/share/user-tmpfiles.d/ this user
/etc/xdg/user-tmpfiles.d/ all users, admin
/usr/share/user-tmpfiles.d/ all users, packages

Units (in the user’s systemd instance):

  • systemd-tmpfiles-setup.service: at login
  • systemd-tmpfiles-clean.timer: periodic cleanup

Example: clean ~/Downloads and ~/.cache automatically:

# ~/.config/user-tmpfiles.d/cleanup.conf
e %h/Downloads - - - 30d
e %C           - - - 60d

Check and apply:

systemd-tmpfiles --user --dry-run --clean
systemctl --user enable --now systemd-tmpfiles-clean.timer

11. tmpfiles.d vs unit directives#

For a directory used by a single service, unit directives are usually simpler:

[Service]
RuntimeDirectory=myapp        # /run/myapp, removed when the service stops
StateDirectory=myapp          # /var/lib/myapp
CacheDirectory=myapp          # /var/cache/myapp
LogsDirectory=myapp           # /var/log/myapp
RuntimeDirectoryMode=0750

They create the directory with the service user as owner and work with DynamicUser=.

Use tmpfiles.d when:

  • the path must exist before the service starts, or without any service
  • several services or users share the path
  • cleanup by age is needed
  • the path must survive service restarts (RuntimeDirectory= is removed on stop unless RuntimeDirectoryPreserve=yes)
  • you need symlinks, copies, ACLs, xattrs, or writes to /sys

12. Gotchas#

  • Same file name = full replacement. /etc/tmpfiles.d/tmp.conf hides every line of /usr/lib/tmpfiles.d/tmp.conf, not just the one you changed.
  • f does not overwrite. If the file already exists, the content is ignored. Use f+ or w to enforce it.
  • Z with a plain mode makes every file executable if the mode has x. Use ~ or z on the top directory only.
  • d fixes permissions every time it runs. If an application changes them deliberately, use :0750 so the mode is set only on creation.
  • Cleanup by atime. With noatime or relatime atime is updated rarely or never. Files that are read often may still look old. Use the m: / mM: prefix if only modification matters.
  • Long running jobs in /tmp. A file unchanged for 10 days can be removed while a process still has it open. Lock the directory with flock or exclude it with x.
  • Service user does not exist yet. The line fails. Ship a sysusers.d file next to the tmpfiles.d file.
  • PrivateTmp=yes. The service sees its own /tmp, lines for /tmp/... affect the host /tmp, not the private one.
  • Syntax errors do not stop processing. Bad lines are skipped and logged. Check after editing:
systemd-tmpfiles --create --dry-run /etc/tmpfiles.d/myapp.conf

References#

  • man 5 tmpfiles.d
  • man 8 systemd-tmpfiles
  • man 5 sysusers.d
  • man 5 systemd.exec (RuntimeDirectory= and friends)