Using Systemd to Start a Python Application with Virtualenv

Systemd is great for starting and stopping services under Linux. When you want to start a Python application that uses virtualenv, you need to take special care. This article explains how to create a systemd script using the example of the open source Timetagger Python application.

Systemd

On Linux systems, systemd is an init system used to bootstrap userspace and manage user processes. At the time of its introduction it was controversial, but now is used by the majority of all modern Linux distributions.

So when you want to automatically run an application at every start of the Linux operating system, you need to create a configuration file. I show later how to do that.

Virtualenv

When installing Python applications that have library dependencies, it is very useful to use the service of virtualenv. With the help of virtualenv you can isolate Python applications so that the library dependencies do not interfere with each other. This is needed if you have more Python applications installed at the same time in your system. Since Python 3.3, a subset of virtualenv is integrated under the venv module.

Timetagger

Timetagger is an open source Python time tracker application developed by Almar Klein. I use this as an example here because I find Timetagger useful in my work. It features a comfortable web interface to track your time and also has an API. Using the Timetagger CLI you can start and stop time tracking on the command line. This is especially handy for software developers.

When you host the application yourself, you probably want to run it automatically at every start of your system. That is where the systemd script comes into play.

Systemd Script

You need to install Timetagger with virtualenv in order to use the systemd script.

After you have cloned Timetagger from GitHub, you can run the following commands to install it using virtualenv:

cd timetagger

python3 -m venv venv

. venv/bin/activate

pip3 install -r requirements.txt

Now all the dependencies are installed using virtualenv.

You need to create the systemd service script (timetagger.service) in the system directory using a text editor:

/etc/systemd/system/timetagger.service

[Unit]
Description=Timetagger service

[Service]
User=Your Linux user name
WorkingDirectory=Your timetagger folder
ExecStart=Your timetagger folder/venv/bin/python3 -m timetagger

[Install]
WantedBy=multi-user.target

Replace Your timetagger folder with the actual Timetagger directory name on you system.

I use the & at the end of the command to make Timetagger run in the background.

The key to running a Python application that has been installed via virtualenv is to execute Python via the venv/bin folder. Then the correct set of libraries are used.

Note that you need admin rights to create the timetagger.service file.

You can now start timetagger with:

sudo systemctl start timetagger

In order to run timetagger automatically at every system start enable it like so:

sudo systemctl enable timetagger

Stopping Timetagger

When you have started Timetagger in the manner described above, you can stop it by sending it a SIGSTOP signal:

kill -SIGSTOP pid

You can get the pid (process id) via the ps ax command. Look for the Timetagger name.

Conclusion

Running Python applications that use virtualenv automatically in systemd is not rocket science. I hope with this article I have shown you how to do it.

Updated 18. April 2023.

References

• Systemd: https://systemd.io/

• Python: https://www.python.org/

• Virtualenv: https://virtualenv.pypa.io/en/latest/

• Timetagger: https://github.com/almarklein/timetagger

• Cover image by OpenAI Dall-E2: "Yellow snake with a time tagger."