Installation
Choose between an automated script or a manual deployment sequence from source code.
Quick Install (Arch)
For a rapid deployment on Arch Linux distributions, you can stream the setup script directly:
curl -fsSL https://raw.githubusercontent.com/caffyne-org/caffyne-shell/main/install.sh | bash
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,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
fabric-cli manually. Find the repository here: https://github.com/Fabric-Development/fabric-cliClone 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:
./start.sh
source venv/bin/activate
python3 main.py
Python Dependencies Reference
Here is the exact dependency locked tree manifest for the runtime environment:
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