Skip to content

Installation Guide

Setting up Pimarchy is a simple, automated process. Follow these steps to transform your Raspberry Pi 5.

Step 1: Flash Pi OS Lite

Download and flash Raspberry Pi OS Lite (64-bit) using the Raspberry Pi Imager.

  1. Select OS: Raspberry Pi OS (other) → Raspberry Pi OS Lite (64-bit).
  2. Select Storage: Choose your MicroSD or SSD.
  3. Click the Gear Icon (Advanced Settings):
    • Set Hostname: (e.g., pimarchy)
    • Set Username and Password: (e.g., ret)
    • Configure Wi-Fi: Enter your SSID and password.
    • Set Locale Settings: (e.g., Timezone and Keyboard layout).
    • Enable SSH: (Optional, if you want to connect remotely).

Step 2: First Boot & Update

Boot your Pi. Log in at the TTY prompt and fully update the system:

sudo apt update && sudo apt full-upgrade -y
sudo reboot

Full Upgrade is Critical

A standard sudo apt upgrade is not sufficient. A full-upgrade is required because Pimarchy adds the Debian Sid repository for Hyprland, which often requires resolving new dependency chains.

Step 3: Install Pimarchy

Once your Pi has rebooted, you can install Pimarchy using our automated web installer. This single command will configure Git (prompting for Name/Email if not set), download Pimarchy, and launch the installer.

curl -sL https://raw.githubusercontent.com/raythurman2386/pimarchy/main/netinstall.sh | bash

Before applying any changes, you can run a dry run to see exactly what will be installed by passing the --dry-run flag to the web installer:

curl -sL https://raw.githubusercontent.com/raythurman2386/pimarchy/main/netinstall.sh | bash -s -- --dry-run

Step 4: Installation Options

During the installation, you will be prompted with several options. Alternatively, you can pass these flags directly to the web installer:

1. Performance and Overclocking

The installer will ask how you want to handle CPU performance:

Key Mode Description
g Governor Only Keeps CPU at max clock (2.4 GHz). Safe for all units, no reboot required.
o Overclock Sets arm_freq=2600 (2.6 GHz). Requires active cooling and a reboot.
N Skip Leaves all CPU settings at their defaults.

2. Quiet Mode (Flags)

If you prefer to skip the interactive prompt, you can pass flags directly to the installer:

curl -sL https://raw.githubusercontent.com/raythurman2386/pimarchy/main/netinstall.sh | bash -s -- --performance   # Governor only
curl -sL https://raw.githubusercontent.com/raythurman2386/pimarchy/main/netinstall.sh | bash -s -- --overclock     # Governor + 2.6 GHz Overclock

Step 5: Final Reboot

Once the script completes, perform one last reboot:

sudo reboot

After rebooting, you will be greeted by the Tuigreet login manager. Log in with your username and password, and Hyprland will start automatically.

Optional: Enable Auto-Login

If you want your Pi to automatically login and start Hyprland on boot (useful for headless setups or ensuring services always start after a reboot), run:

sudo bash enable-autologin.sh

This configures greetd to skip the login prompt and automatically start the desktop environment for your user. To disable auto-login later, re-run the Pimarchy installer.

Managing Pimarchy (CLI Tool)

Once installed, Pimarchy includes a global CLI tool to easily manage updates and configurations.

# Fetch the latest version from GitHub and apply new configurations
pimarchy update

# Validate your current template configurations
pimarchy validate

# Re-run the installer (e.g. to apply a new theme.conf)
pimarchy install

# Uninstall Pimarchy and restore original config backups
pimarchy uninstall

Advanced: Manual Setup

If you prefer to clone and run the installer manually:

sudo apt install -y git
git clone https://github.com/raythurman2386/pimarchy.git ~/.local/share/pimarchy
cd ~/.local/share/pimarchy
bash install.sh

What Happens During Installation?

  1. Backup: Backs up your existing configs to ~/.config/Pimarchy-backup/.
  2. Repo Setup: Adds Debian Sid (for Hyprland) and Docker CE repositories.
  3. Package Management: Installs over 30 packages including Wayland, Hyprland, and Alacritty.
  4. Theming: Deploys configurations based on the Ravenwood palette in config/theme.conf.
  5. Services: Enables and configures greetd as the system's login manager.
  6. AI Tools: Installs the OpenCode agent into ~/.opencode/.