← All tools

systemd Unit Name Escaper

Turn an absolute path or a piece of text into the reversible unit name systemd expects, or decode an escaped name back to its path or text. Everything is computed locally.

The path is normalized and joined with hyphens, as in /var/lib/postgresql.

Appended after the escaped name, for example .mount; encoding and decoding treat it as separate from the escaped body.

How the escaping works

A unit name may contain only A–Z, a–z, 0–9, ':', '_' and '.'; a leading dot is escaped.
CharacterWritten asReason
/-Path separator, so path components join with one hyphen.
-\x2dA literal hyphen must not be mistaken for a path separator.
space\x20Spaces are not allowed in a unit name.
@\x40@ separates a template name from its instance.
%\x25% introduces a unit-name specifier.
. (first)\x2eA unit name may not begin with a dot.
é\xc3\xa9Non-ASCII characters are escaped byte by byte as UTF-8.

The escaping is the one performed by systemd-escape: a slash becomes a hyphen, and because a hyphen in the escaped name always means a slash, a literal hyphen is written \x2d. Path mode requires an absolute, normalized path — duplicate slashes and . components are removed, while any .. component is refused instead of simplified. Decoding is stricter than the command: the input must look like an escaped name, so characters such as a space, slash or @ are rejected until they are escaped. Unit names are limited to 255 characters including the type suffix. This page reads and writes text only: it executes nothing, installs nothing, stores nothing and never contacts the network.