Your company here — click to reach over 10,000 unique daily visitors

systemd.v - Man Page

Directory with Versioned Resources


In various places systemd components accept paths whose trailing components have the ".v/" suffix, pointing to a directory. These components will then automatically look for suitable files inside the directory, do a version comparison and open the newest file found (by version). Available since version v256. Specifically, two expressions are supported:

To illustrate this in an example, consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with three files:

Invoke a tool such as systemd-nspawn(1) with a command line like the following:

# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v --boot

Then this would automatically be resolved to the equivalent of:

# systemd-nspawn --image=/var/lib/machines/mymachine.raw.v/mymachine_7.6.0.raw --boot

Much of systemd's functionality that expects a path to a disk image or OS directory hierarchy support the ".v/" versioned directory mechanism, for example systemd-nspawn(1), systemd-dissect(1) or the RootDirectory=/RootImage= settings of service files (see systemd.exec(5)).

Use the systemd-vpick(1) tool to resolve ".v/" paths from the command line, for example for usage in shell scripts.

Filtering and Sorting

The variable part of the filenames in the ".v/" directories are filtered and compared primarily with a version comparison, implementing Version Format Specification[1]. However, additional rules apply:

Or in other words, the files in the ".v/" directories should follow one of these naming structures:


Here's a more comprehensive example, further extending the one described above. Consider a directory /var/lib/machines/mymachine.raw.v/, which is populated with the following files:

Now invoke the following command on an x86-64 machine:

$ systemd-vpick --suffix=.raw /var/lib/machines/mymachine.raw.v/

This would resolve the specified path to /var/lib/machines/mymachine.raw.v/mymachine_7.5.14_x86-64.raw. Explanation: even though mymachine_7.7.0_x86-64+0-5.raw has the newest version, it is not preferred because its tries left counter is zero. And even though mymachine_7.6.0_arm64.raw has the second newest version it is also not considered, in this case because we operate on an x86_64 system and the image is intended for arm64 CPUs. Finally, the mymachine_7.5.13.raw image is not considered because it is older than mymachine_7.5.14_x86-64.raw.

See Also

systemd(1), systemd-vpick(1), systemd-nspawn(1), systemd-dissect(1), systemd.exec(5), systemd-sysupdate(1)


  1. Version Format Specification
  2. Automatic Boot Assessment

Referenced By

org.freedesktop.portable1(5), portablectl(1), systemd.directives(7), systemd-dissect(1), systemd.exec(5), systemd.index(7), systemd-nspawn(1), systemd-vpick(1).

systemd 256