MotionPaper is a Tkinter GUI for applying wallpapers from Steam Wallpaper Engine through linux-wallpaperengine.

Note that this was developed with the caelestia rice in mind. Hyprpaper support is extremely experimental and not tested, therefore pull requests for Hyprpaper support (as well as other wallpaper backends) are welcome.

pipx is the recommended Linux install path:

1. Install pipx (once):

# Debian/Ubuntu
sudo apt install pipx
pipx ensurepath

2. Install MotionPaper from GitHub:

pipx install "git+https://github.com/kaemori/motionpaper.git"

3. Install desktop entries:

motionpaper-install

This installs both launcher apps: motionpaper and motionpaper-daemon.

4. Launch:

motionpaper

For a one-command install flow, use the bootstrap installer script:

curl -fsSL https://raw.githubusercontent.com/kaemori/motionpaper/main/install.sh | bash

You can also run it with an explicit repository URL:

curl -fsSL https://raw.githubusercontent.com/kaemori/motionpaper/main/install.sh | bash -s -- "git+https://github.com/kaemori/motionpaper.git"

• motionpaper: launch the GUI
• motionpaper-daemon: launch the daemon only
• motionpaper-install: install desktop entries under ~/.local/share/applications
• motionpaper-uninstall: remove desktop entries/icon and stop daemon

When installed with pipx, MotionPaper is installed as a user app (not system-wide):

• Executables are exposed in ~/.local/bin (for example motionpaper)
• App venv lives under ~/.local/pipx/venvs/motionpaper
• Desktop entries are written to ~/.local/share/applications/motionpaper.desktop and ~/.local/share/applications/motionpaper-daemon.desktop
• App icon is copied to ~/.local/share/icons/hicolor/256x256/apps/motionpaper.png
• Runtime config is stored in ~/.config/motionpaper

1. Remove desktop integration and stop daemon:

motionpaper-uninstall

2. Remove config too (optional):

motionpaper-uninstall --purge-config

3. Uninstall package and commands:

pipx uninstall motionpaper

4. Wrapper script (optional, does both cleanup + pipx uninstall):

./uninstaller.sh

If you are developing from source, you can still run the compatibility scripts:

./launch.sh
./daemon.sh
./install_to_desktop.sh

The launcher scripts prefer ./.venv/bin/python3 when present and fall back to python3 from your PATH.

motionpaper/
├── motionpaper/                  # Python package (shared app logic)
│   ├── config_store.py           # Config and themes loading/saving
│   ├── constants.py              # Paths, version, and app constants
│   ├── daemon_control.py         # GUI-facing daemon start/stop helpers
│   ├── daemon_runtime.py         # Daemon implementation
│   ├── gui_helpers.py            # Shared UI utility functions
│   ├── installer.py              # pipx-friendly desktop entry installer
│   ├── uninstaller.py            # pipx-friendly desktop integration cleanup
│   ├── romanization.py           # JP/CN/KR title romanization
│   ├── wallpaper_library.py      # Workshop wallpaper metadata loader
│   └── resources/
│       ├── icon.png              # Packaged icon used by motionpaper-install
│       └── themes.json           # Packaged themes used at runtime
├── gui.py                        # GUI entrypoint module
├── main.py                       # Daemon entrypoint module
├── pyproject.toml                # Packaging metadata and entry points
├── install.sh                    # Curl/bootstrap installer
├── uninstaller.sh                # Uninstalls pipx package and local desktop integration
├── scripts/
│   ├── launch_gui.sh
│   ├── launch_daemon.sh
│   └── install_desktop_entries.sh
├── desktop/
│   ├── motionpaper.desktop
│   └── motionpaper-daemon.desktop
├── assets/
│   └── icon.png
├── config/
│   └── themes.json
├── launch.sh                     # Compatibility wrapper -> scripts/launch_gui.sh
├── daemon.sh                     # Compatibility wrapper -> scripts/launch_daemon.sh
└── install_to_desktop.sh         # Compatibility wrapper -> scripts/install_desktop_entries.sh

• Config is stored at ~/.config/motionpaper/config.json.
• The daemon PID file is stored at /tmp/motionpaper-daemon.pid.
• Wallpaper discovery uses Steam workshop path ~/.local/share/Steam/steamapps/workshop/content/431960.