Getting Started

Installation

Get caffyne shell up and running on your system.

Choose between an automated script or a manual deployment sequence from source code.

Quick Install

Select your distribution to quickly install Caffyne Shell using package managers or setup scripts.

Arch

curl -fsSL https://raw.githubusercontent.com/caffyne-org/caffyne-shell/main/install.sh | bash

Fedora

# 1. Enable COPR repository
sudo dnf copr enable caffyne/caffyne-shell

# 2. Install caffyne-shell
sudo dnf install -y caffyne-shell

Debian

# 1. Create keyring directory & add GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://caffyne-org.github.io/caffyne-debian/caffyne-apt.gpg.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/caffyne.gpg > /dev/null

# 2. Add repository to sources list
echo "deb [signed-by=/etc/apt/keyrings/caffyne.gpg] https://caffyne-org.github.io/caffyne-debian trixie main" | sudo tee /etc/apt/sources.list.d/caffyne.list

# 3. Update package lists & install caffyne-shell
sudo apt-get update
sudo apt-get install -y caffyne-shell

Ubuntu

# 1. Create keyring directory & add GPG key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://caffyne-org.github.io/caffyne-debian/caffyne-apt.gpg.pub | gpg --dearmor | sudo tee /etc/apt/keyrings/caffyne.gpg > /dev/null

# 2. Add repository to sources list
echo "deb [signed-by=/etc/apt/keyrings/caffyne.gpg] https://caffyne-org.github.io/caffyne-debian noble main" | sudo tee /etc/apt/sources.list.d/caffyne.list

# 3. Update package lists & install caffyne-shell
sudo apt-get update
sudo apt-get install -y caffyne-shell

Nix / NixOS

# 1. Clone the repository into target directory
git clone https://github.com/caffyne-org/caffyne-shell.git ~/.config/caffyne-shell

# 2. Navigate to directory
cd ~/.config/caffyne-shell

# 3. Execute profile installation via Nix
nix profile install

Manual Installation

Follow these steps to set up the environment manually on your system.

Install System Dependencies

Ensure the following packages are compiled and accessible within your distribution path:

  • Core Core Libraries: gtk3, awww, matugen, cairo, libgirepository
  • Introspection Runtimes: gobject-introspection, gobject-introspection-runtime, gtk-layer-shell, gtk-session-lock, libdbusmenu-gtk3
  • Desktop & Playback Services: cinnamon-desktop, playerctl, fabric-cli
  • Python Ecosystem: python, python-pip, python-venv
  • Hardware Integration Protocols: gnome-bluetooth-3.0, bluez, bluetoothctl, brightnessctl, wf-recorder, networkmanager, upower
Non-Arch Linux users may need to compile fabric-cli manually. Find the repository here: https://github.com/Fabric-Development/fabric-cli

Clone the Repository

Clone the project structure explicitly into your configuration path:

git clone https://github.com/caffyne-org/caffyne-shell.git ~/.config/caffyne-shell
cd ~/.config/caffyne-shell

Create Virtual Environment

Isolate your workspace dependencies by instantiating a python virtual environment:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Compile C/GTK Libraries

Compile the performance-critical submodules included inside the shell snippets path:

cd ~/.config/caffyne-shell/snippets/blur/lib
make
cd ~/.config/caffyne-shell/snippets/hacktk/lib
make

Matugen Integration

Follow these steps to install the Caffyne template and hook it into your Matugen configuration tree.

Create Template Directories

First, ensure that Matugen's local configuration and template paths exist in your home directory:

mkdir -p ~/.config/matugen

Update Matugen Configuration

Open your Matugen configuration file located at ~/.config/matugen/config.toml and append the template mapping block.

[config] # Include this if it's not already in your file

# caffyne shell Color Generation
[templates.caffyne]
input_path = '~/.config/caffyne-shell/matugen/caffyne-shell-colors.css'
output_path = '~/.config/caffyne-shell/style/colors.css'

Trigger Color Generation

Run Matugen as you normally do to change your wallpaper or colors. Matugen will now automatically parse the template and compile your new active colors directly into:

~/.config/caffyne-shell/style/colors.css

Executing shell

You can initialize the runtime thread either via the provided helper engine script or raw execution commands:

caffyne-shell

Python Dependencies Reference

Here is the exact dependency locked tree manifest for the runtime environment:

requirements.txt
cffi==2.0.0
click==8.4.1
fabric @ git+https://github.com/Fabric-Development/fabric.git@23cab85fc61f1cdbb5f60db0027dc57026ba05b7
loguru==0.7.3
pam==0.2.0
pillow==12.2.0
psutil==7.2.2
pycairo==1.29.0
pycparser==3.0
PyGObject==3.50.0
python-pam==2.0.2
RapidFuzz==3.14.5
setproctitle==1.3.7
six==1.17.0
thefuzz==0.22.1

Introduction

Welcome to caffyne shell, a modern, highly customisable desktop built for Wayland.

Autostart

Learn how to configure caffyne shell to hook into your compositor session.