Skip to content
Tsumiki

Installation


Prerequisites

Section titled “Prerequisites”

Ensure these are installed before proceeding:

| Requirement | Install Command (Arch Linux) | Notes | | ———————————————— | —————————————–– | ––––––––––––––––– | –––––––––––––––––––––––––– | | Hyprland | sudo pacman -S hyprland | Running Hyprland instance required | | JetBrains Nerd Font | sudo pacman -S ttf-jetbrains-mono-nerd | Needed for icon rendering | | Python 3.12+ | sudo pacman -S python | Verify: python --version | | uv | curl -LsSf https://astral.sh/uv/install.sh | sh | Python package manager used by ./tsumiki.sh -setup | | Git | sudo pacman -S git | Required for cloning | | NetworkManager | sudo pacman -S networkmanager | Required by network widgets | | PipeWire | sudo pacman -S pipewire pipewire-pulse | Required by audio widgets |

Clone

Section titled “Clone”
Terminal window
git clone https://github.com/rubiin/tsumiki.git ~/.config/tsumiki
cd ~/.config/tsumiki

Latest Release

Section titled “Latest Release”
Version:v4.4.0Date:2026-08-20

For full release notes and assets, see the releases page on GitHub.

Installation Options

Section titled “Installation Options”

Choose one of the following three methods.

Option 1: Bootstrap Script (Fastest)

Section titled “Option 1: Bootstrap Script (Fastest)”
Terminal window
curl -fsSL https://raw.githubusercontent.com/rubiin/tsumiki/master/install.sh | bash

This script clones or updates ~/.config/tsumiki, then runs the full setup.

To install and start immediately:

Terminal window
curl -fsSL https://raw.githubusercontent.com/rubiin/tsumiki/master/install.sh | bash -s -- --start

Option 2: Automated Setup in Existing Clone

Section titled “Option 2: Automated Setup in Existing Clone”

If you already cloned the repo manually, run the setup script:

Terminal window
./tsumiki.sh -setup
./tsumiki.sh -start

The -setup flag installs required system packages and configures the Python virtual environment.

Option 3: Manual Dependency Setup

Section titled “Option 3: Manual Dependency Setup”

Prefer full control over packages? Install dependencies yourself and then start:

Terminal window
# Install system packages
sudo pacman -S --noconfirm --needed \
  pipewire playerctl dart-sass power-profiles-daemon networkmanager \
  brightnessctl pkgconf wf-recorder kitty python pacman-contrib \
  gtk3 cairo gtk-layer-shell libgirepository noto-fonts-emoji \
  gobject-introspection gobject-introspection-runtime uv \
  python-gobject python-psutil python-cairo python-loguru libnotify \
  cliphist libqalculate python-httpx satty nvtop


# Install AUR packages (using yay as example)
yay -S --needed \
  python-fabric-git gnome-bluetooth-3.0 python-rlottie-python \
  python-pytomlpp slurp imagemagick tesseract tesseract-data-eng \
  ttf-jetbrains-mono-nerd grimblast-git python-ijson


# Install Python deps
uv sync


# Start
./tsumiki.sh -start

If you do not use yay, install the AUR packages with your preferred AUR helper.

Autostart Configuration

Section titled “Autostart Configuration”

Add this line to your ~/.config/hypr/hyprland.conf to launch Tsumiki automatically when Hyprland starts:

Terminal window
exec-once = sleep 5; ~/.config/tsumiki/tsumiki.sh -start

The sleep 5 ensures Hyprland is fully initialized before Tsumiki launches. Adjust the path if you cloned to a different location.

Verifying the Installation

Section titled “Verifying the Installation”
  1. Run ./tsumiki.sh -start from the project directory.
  2. The Tsumiki bar should appear at the top of your screen.
  3. If you see error messages, check that:
    • All system packages are installed (./tsumiki.sh -setup re-runs this check)
    • Python dependencies are installed (uv sync)
    • You’re running under Hyprland (not another compositor or X11)

If the bar doesn’t appear, see Troubleshooting.

After Install

Section titled “After Install”

Continue with Post Installation for Hyprland layer rules and First Steps to configure your panel.