You need a service that runs under your user, not root
You installed a development tool or a personal container that needs to run whenever you log into your desktop. You don't want to run it as root, and you don't want to type a command every time you open your laptop. You tried putting a service file in /etc/systemd/system/ and got a permission denied error, or you realized the service starts before you even log in, which breaks your user-specific environment variables. You need a service that lives in your home directory, starts with your session, and respects your user permissions.
How user services differ from system services
Systemd runs two separate managers on your machine. The system manager starts at boot and handles global services like networking, storage, and the display server. It runs as root. The user manager starts when you log in. It handles services that belong to you, like a personal web server, a database for your projects, or a container that needs access to your home directory. The user manager runs under your user ID. It cannot touch system resources, and it stops when you log out. This separation keeps your personal experiments from breaking the OS and keeps the OS from breaking your experiments.
Think of the system manager as the building's HVAC. It runs whether anyone is in the office, and it controls the whole structure. The user manager is your desk lamp. It only turns on when you sit down, it only lights up your desk, and you can unplug it without affecting the rest of the floor.
Reload the daemon after every config change. systemd won't guess that you added a file.
Quadlet files generate the service for you
Quadlet files are not systemd unit files. They are declarative configuration files that a generator reads to produce actual unit files. When you place a file like myapp.container in the correct directory, a generator scans it, translates the container directives into systemd syntax, and writes a temporary .service file into a runtime directory. You manage the .container file. systemd manages the generated .service file. Never edit the generated file. It will be overwritten on the next reload.
This separation means you can change the image or add a port mapping in the .container file, reload, and systemd updates the service definition instantly. You don't need to understand systemd unit syntax to run containers. The generator translates container concepts into systemd directives automatically.
The service name is derived from the filename with a prefix. A file named myapp.container generates a unit called containers-myapp.service. The prefix containers- is added by the generator. If you try to start myapp.service, systemd will report that the unit is not found. Check the generated name before you start the service.
Create and start the service
Create the configuration directory and write a Quadlet file to define your container service. The directory must exist for the generator to find your files.
mkdir -p ~/.config/containers/systemd
# WHY: Creates the directory structure if it doesn't exist.
# Podman and systemd look here for user-level container definitions.
cat > ~/.config/containers/systemd/myapp.container <<EOF
[Container]
Image=quay.io/libpod/fedora_podman:latest
# WHY: Specifies the container image to pull and run.
# Replace this with your actual image name.
EOF
Reload the user manager to pick up the new file and start the service. The reload triggers the generator to create the unit file.
systemctl --user daemon-reload
# WHY: Tells the user manager to rescan configuration directories.
# Without this, systemd ignores the new file you just created.
systemctl --user start containers-myapp
# WHY: Starts the generated service.
# The name 'containers-myapp' comes from the filename 'myapp.container'.
Use systemctl --user for all commands. Never use sudo with --user. The --user flag tells systemd to talk to your session manager, not the system manager. If you mix them, you get confusing errors or the command silently does nothing. Use systemctl --user enable <service> to make the service start automatically when you log in.
Check the generated unit name. The prefix changes how you address the service.
Verify the service is running
Check the service status and view logs to confirm the container is running correctly. User logs live in a separate journal from system logs.
systemctl --user status containers-myapp
# WHY: Shows the current state, recent log lines, and whether the service is active.
journalctl --user -u containers-myapp -n 10
# WHY: Dumps the last 10 log lines for this specific user service.
# Use -xe to add explanatory hints if the output is unclear.
Running journalctl without --user shows system logs and will not show your container output. Always use journalctl --user or journalctl --user -u <service> to debug user services. The systemctl --user status command shows recent log lines and state in one view. Check status before you restart anything.
Common errors and how to fix them
If you see Failed to start containers-myapp.service: Unit containers-myapp.service not found, you likely forgot to run daemon-reload or you are using the wrong service name. Run systemctl --user daemon-reload and verify the name with systemctl --user list-units | grep myapp. The generator only runs on reload or when the manager starts.
If the service fails immediately after starting, check the logs for image pull errors. The generator creates the service, but the container runtime still needs to pull the image. If you are disconnected from the network, the service will enter a failed state. Run podman pull manually to cache the image, then restart the service.
If you see permission errors when starting the service, check the ownership of your configuration files. The user manager requires that files in ~/.config/containers/systemd/ are owned by your user. If you copied files from a root directory or used sudo to create them, the manager may refuse to load them. Run chown -R $USER:$USER ~/.config/containers to fix ownership.
User services stop when you log out. Enable them if you need persistence across reboots.
When to use user services vs system services
Use user services when the workload needs access to your home directory, your SSH keys, or your user environment variables. Use system services when the workload must run before anyone logs in, requires root privileges, or provides a network service to other machines. Use Quadlet files when you are managing containers with Podman. The generator handles the boilerplate, mounts, and restart policies automatically. Write manual .service files when you are running a custom script or binary that does not involve containers. Enable the service with systemctl --user enable when you want it to start on login. Start the service manually with systemctl --user start when you only need it for the current session.