Home » Where do I put my systemd unit file?

Where do I put my systemd unit file?


The best place to put system unit files: /etc/systemd/system
Just be sure to add a target under the [Install] section, read “How does it know?” for details. UPDATE: /usr/local/lib/systemd/system is another option, read “Gray Area” for details.”

The best place to put user unit files: /etc/systemd/user or $HOME/.config/systemd/user
but it depends on permissions and the situation.

The truth is that systemd units (or as the intro sentence calls them, “unit configurations”) can go anywhere—provided you are willing to make manual symlinks and you are aware of the caveats. It makes life easier to put the unit where systemctl daemon-reload can find it for some good reasons:

  • Using a standard location means that systemd generators will find them and make them easy to enable at boot with systemctl enable. This is because your unit will automatically be added to a unit dependency tree (a unit cache).
  • You do not need to think about permissions, because only the right privileged users can write to the designated areas.

How does it know?

And how exactly does systemctl enable know where to create the symlink? You hard code it within the
unit itself under the [install] section. Usually there is a line like

WantedBy = multi-user.target

that corresponds to a predefined place on the filesystem.
This way, systemctl knows that this unit is dependent on a group of unit files called multi-user.target (“target” is the term used to designate unit dependency groups. You can list all groups with systemctl list-units --type target). The group of unit files to be loaded with a target is put in a targetname.target.wants directory. This is just a directory full of symlinks (or the real thing). If your [Install] section says it is WantedBy the multi-user.target, but if a symlink to it does not exist in the multi-user.target.wants directory, then it will not load. When the systemd unit generators add your unit file to the dependency tree cache at boot (you can manually trigger generators with systemctl daemon-reload), it automatically knows where to put the symlink—in this case in the directory /etc/systemd/system/multi-user.target.wants/ should you enable it.

Key Points in the Manual:

Additional units might be loaded into systemd (“linked”) from
directories not on the unit load path. See the link command for

Under systemctl, look for Unit File Commands

Unit File Load Path

Please read and understand the first sentence in the following quote from man systemd.unit (because it implies that all of the paths I mention here may not apply to you if your systemd was compiled with different paths):

Unit files are loaded from a set of paths determined during compilation, described in the two tables below. Unit files found in directories listed earlier override files with the same name in directories lower in the list.

When the variable $SYSTEMD_UNIT_PATH is set, the contents of this variable overrides the unit load path. If $SYSTEMD_UNIT_PATH ends with an empty component (“:”), the usual unit load path will be appended to the contents of the variable.

Table 1 and Table 2 from man systemd.unit are good.

Load paths when running in system mode (--system).

  • /etc/systemd/system Local configuration
  • /run/systemd/system Runtime units
  • /usr/lib/systemd/system Units of installed packages (or /lib/systemd/system in some cases, read man systemd.unit)

Load path when running in user mode (--user)

There is a difference between per user units and all/global users units.


  • $XDG_CONFIG_HOME/systemd/user User configuration (only used when $XDG_CONFIG_HOME is set)

  • $HOME/.config/systemd/user User configuration (only used when $XDG_CONFIG_HOME is not set)

  • $XDG_RUNTIME_DIR/systemd/user Runtime units (only used when $XDG_RUNTIME_DIR is set)

  • $XDG_DATA_HOME/systemd/user Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is set)

  • $HOME/.local/share/systemd/user Units of packages that have been installed in the home directory (only used when $XDG_DATA_HOME is not set)

--global (all users)

Units that apply to all users–meaning owned by each user, too. So each user can stop these services even if an administrator enables them at boot.

  • /etc/systemd/user Local configuration for all users (systemctl --global enable userunit.service)
  • /usr/lib/systemd/user Units of packages that have been installed system-wide for all users (or /lib/systemd/system in some cases, read man systemd.unit)
  • /run/systemd/user Runtime units

Gray Area

On the one hand, the File Hierarchy Standard (also man file-hierarchy) specifies that /etc is for local configurations that do not execute binaries. On the other hand
it specifies that /usr/local/ “is for use by the system administrator when installing software locally”. You could also argue (if not just for the purpose of organization) that all system unit files should go under /usr/local/lib/systemd/system, but this is intended for unit files that are part of “software” not from a package manager.
The corresponding systemd user units that are system-wide could go under

Transient Unit

Another forgotten place is nowhere at all! Perhaps a lesser-known program is systemd-run. You can use it to run transient units on the fly. see man systemd-run.

For example, to schedule a reboot tomorrow morning at 4 a.m. (you might need --force to ensure a reboot happens):

systemd-run -u restart --description="Restarts machine" --on-calendar="2020-12-18 04:00:00" systemctl --force reboot

This will yield a transient unit file restart.service and a corresponding timer (because of the --on-calendar, indicated by transient=yes.


# This is a transient unit file, created programmatically via the systemd API. Do not edit.
Description=Restarts machine

ExecStart="/usr/bin/systemctl" "--force" "reboot"

Note that there is also the more dangerous double force option --force --force, which tells the kernel to halt immediately (and, if you do not know what you’re doing, unsafely, because it is almost equivalent to cutting the power).

/etc/systemd/system is where you put your scripts, pacman puts package scripts in /usr/lib/systemd/system.

Issuing systemctl enable foo.service creates symlinks from /usr to /etc. See the Unit Load Path section of man systemd.unit(5) for more detail.

One noticeable difference between /etc/systemd/system and /lib/systemd/system on Debian/Ubuntu system is, the service files under /lib/systemd/system can be masked while those under /etc/systemd/system cannot. For example,

# ls /lib/systemd/system/mytest.service
# systemctl mask mytest
# ls /etc/systemd/system/mytest2.service
# systemctl mask mytest2
Failed to mask unit: File /etc/systemd/system/mytest2.service already exists.

Related Solutions

Joining bash arguments into single string with spaces

[*] I believe that this does what you want. It will put all the arguments in one string, separated by spaces, with single quotes around all: str="'$*'" $* produces all the scripts arguments separated by the first character of $IFS which, by default, is a space....

AddTransient, AddScoped and AddSingleton Services Differences

TL;DR Transient objects are always different; a new instance is provided to every controller and every service. Scoped objects are the same within a request, but different across different requests. Singleton objects are the same for every object and every...

How to download package not install it with apt-get command?

Use --download-only: sudo apt-get install --download-only pppoe This will download pppoe and any dependencies you need, and place them in /var/cache/apt/archives. That way a subsequent apt-get install pppoe will be able to complete without any extra downloads....

What defines the maximum size for a command single argument?

Answers Definitely not a bug. The parameter which defines the maximum size for one argument is MAX_ARG_STRLEN. There is no documentation for this parameter other than the comments in binfmts.h: /* * These are the maximum length and maximum number of strings...

Bulk rename, change prefix

I'd say the simplest it to just use the rename command which is common on many Linux distributions. There are two common versions of this command so check its man page to find which one you have: ## rename from Perl (common in Debian systems -- Ubuntu, Mint,...

Output from ls has newlines but displays on a single line. Why?

When you pipe the output, ls acts differently. This fact is hidden away in the info documentation: If standard output is a terminal, the output is in columns (sorted vertically) and control characters are output as question marks; otherwise, the output is...

mv: Move file only if destination does not exist

mv -vn file1 file2. This command will do what you want. You can skip -v if you want. -v makes it verbose - mv will tell you that it moved file if it moves it(useful, since there is possibility that file will not be moved) -n moves only if file2 does not exist....

Is it possible to store and query JSON in SQLite?

SQLite 3.9 introduced a new extension (JSON1) that allows you to easily work with JSON data . Also, it introduced support for indexes on expressions, which (in my understanding) should allow you to define indexes on your JSON data as well. PostgreSQL has some...

Combining tail && journalctl

You could use: journalctl -u service-name -f -f, --follow Show only the most recent journal entries, and continuously print new entries as they are appended to the journal. Here I've added "service-name" to distinguish this answer from others; you substitute...

how can shellshock be exploited over SSH?

One example where this can be exploited is on servers with an authorized_keys forced command. When adding an entry to ~/.ssh/authorized_keys, you can prefix the line with command="foo" to force foo to be run any time that ssh public key is used. With this...

Why doesn’t the tilde (~) expand inside double quotes?

The reason, because inside double quotes, tilde ~ has no special meaning, it's treated as literal. POSIX defines Double-Quotes as: Enclosing characters in double-quotes ( "" ) shall preserve the literal value of all characters within the double-quotes, with the...

What is GNU Info for?

GNU Info was designed to offer documentation that was comprehensive, hyperlinked, and possible to output to multiple formats. Man pages were available, and they were great at providing printed output. However, they were designed such that each man page had a...

Set systemd service to execute after fstab mount

a CIFS network location is mounted via /etc/fstab to /mnt/ on boot-up. No, it is not. Get this right, and the rest falls into place naturally. The mount is handled by a (generated) systemd mount unit that will be named something like mnt-wibble.mount. You can...

Merge two video clips into one, placing them next to each other

To be honest, using the accepted answer resulted in a lot of dropped frames for me. However, using the hstack filter_complex produced perfectly fluid output: ffmpeg -i left.mp4 -i right.mp4 -filter_complex hstack output.mp4 ffmpeg -i input1.mp4 -i input2.mp4...

How portable are /dev/stdin, /dev/stdout and /dev/stderr?

It's been available on Linux back into its prehistory. It is not POSIX, although many actual shells (including AT&T ksh and bash) will simulate it if it's not present in the OS; note that this simulation only works at the shell level (i.e. redirection or...

How can I increase the number of inodes in an ext4 filesystem?

It seems that you have a lot more files than normal expectation. I don't know whether there is a solution to change the inode table size dynamically. I'm afraid that you need to back-up your data, and create new filesystem, and restore your data. To create new...

Why doesn’t cp have a progress bar like wget?

The tradition in unix tools is to display messages only if something goes wrong. I think this is both for design and practical reasons. The design is intended to make it obvious when something goes wrong: you get an error message, and it's not drowned in...