Welcome to Hyprotter

Hyprotter is the first complete GUI solution for configuring Hyprland, the dynamic tiling Wayland compositor. This documentation will guide you through everything you need to know.

Why Hyprotter?

Configuring Hyprland manually requires editing ~/.config/hypr/hyprland.conf and understanding the syntax for hundreds of options. Common problems include:

• Black screen after misconfiguration
• Cryptic error messages
• No visual feedback while editing
• Difficulty finding the right options
• Hours of wiki reading to understand each setting

Hyprotter solves all of this by providing a visual interface where you can:

• See changes in real-time with live preview
• Use sliders, color pickers, and dropdowns instead of text editing
• Browse and install community themes with one click
• Never worry about syntax errors again
• Share your configurations with others

Installation

Hyprotter is available for most Linux distributions. Choose your distribution below and follow the instructions.

Binary (All Distributions)

Download the portable binary - works on any Linux distribution:

Tip: Move the binary to ~/.local/bin/ for easy access from anywhere.

Install Script (Recommended)

Our install script automatically downloads the latest version and sets everything up:

The script will:

• Download the latest Hyprotter version
• Install it to ~/.local/bin/
• Create a desktop entry for your application menu
• Set up automatic updates (optional)

Manual Download

You can also download Hyprotter directly from our download page:

• AppImage - Universal, works on all distributions
• .tar.gz - For manual installation

Go to Downloads →

Dependencies

Hyprotter requires the following (installed automatically on most distributions):

• Hyprland - The Wayland compositor itself
• GTK4 - For the graphical interface
• libadwaita - Modern GTK widgets
• hyprctl - For communicating with Hyprland (comes with Hyprland)

First Steps

After installation, here's how to get started with Hyprotter.

Launching Hyprotter

You can launch Hyprotter in several ways:

• From your application menu: Search for "Hyprotter"
• From terminal: Run hyprotter
• With a keybind: Add to your Hyprland config (see below)

Adding a Keybind

Add this line to your ~/.config/hypr/hyprland.conf to launch Hyprotter with Super + H:

First-Run Wizard

When you first launch Hyprotter, you'll be greeted by the First-Run Wizard. This wizard helps you set up the most essential settings:

1. Monitor Configuration
   Set up your displays, resolution, refresh rate, and arrangement.
2. Basic Keybinds
   Configure essential shortcuts like terminal, app launcher, and window management.
3. Appearance
   Choose a color scheme and basic visual settings.
4. Autostart
   Configure applications that should start with Hyprland.

The Main Interface

After the wizard, you'll see the main Hyprotter interface with these areas:

Configuration Sections

Hyprotter organizes Hyprland's configuration into logical sections. Here's what each section contains:

General

Basic window and compositor settings:

• Gaps - Space between windows (inner) and screen edges (outer)
• Border - Window border size and colors (active/inactive)
• Layout - Choose between dwindle (spiral) or master-stack layout
• Cursor - Cursor theme, size, and behavior
• Focus - How focus follows mouse movement

Decoration

Visual effects and window appearance:

• Rounding - Corner radius for windows
• Opacity - Window transparency (active/inactive)
• Blur - Background blur effect settings
• Shadow - Drop shadow size, color, and offset
• Dim - Dim inactive windows

Animations

Configure how windows animate:

• Enabled - Toggle all animations on/off
• Speed - Global animation speed multiplier
• Bezier Curves - Custom easing functions
• Window Animations - Open, close, move effects
• Workspace Animations - Switching between workspaces
• Fade - Fade in/out effects

Input

Keyboard and mouse settings:

• Keyboard Layout - Language, variant, options
• Repeat Rate - Key repeat speed and delay
• Mouse Sensitivity - Acceleration and speed
• Touchpad - Gestures, tap-to-click, scroll direction
• Tablet - Graphics tablet configuration

Keybinds

Keyboard shortcuts for all actions:

• Window Management - Move, resize, close, fullscreen
• Workspace - Switch, move windows between workspaces
• Applications - Launch terminal, browser, file manager
• System - Lock, logout, power menu
• Custom - Add your own shortcuts

Monitor

Display configuration:

• Resolution - Native or custom resolution
• Refresh Rate - Hz setting for each monitor
• Position - Drag and drop monitor arrangement
• Scale - HiDPI scaling factor
• Transform - Rotation (0°, 90°, 180°, 270°)
• Mirroring - Mirror one display to another

Window Rules

Per-application settings:

• Floating - Force windows to float
• Workspace - Open on specific workspace
• Size/Position - Default window dimensions
• Opacity - Per-app transparency
• Animation - Custom animations per window

Window rules can match by window class, title, or other properties. Hyprotter provides a window picker to easily select the target application.

Autostart

Programs that launch with Hyprland:

• Add/remove startup applications
• Set delay before launch
• Configure environment variables
• Run commands once or on every reload

Themes & Library

The Theme Library is where you can discover, download, and install complete Hyprland configurations created by the community.

What's in a Theme?

A Hyprotter theme can include any combination of:

• Hyprland Config - Colors, gaps, animations, keybinds
• Waybar Config - Status bar theme and layout
• Wallpaper - Background image
• Color Scheme - Coordinated colors for all components
• Additional Configs - Rofi, dunst, kitty, etc.

Browsing Themes

Visit the Theme Library to browse available themes. You can:

• Search by name or author
• Filter by tags (minimal, colorful, dark, light)
• Sort by downloads, date, or rating
• Preview screenshots before installing

Installing a Theme

1. Find a theme you like in the Library
2. Click on it to see the detail page
3. Review the included components and screenshots
4. Click "Install Theme"
5. Choose which components to install:
   • Hyprland configuration
   • Waybar (if included)
   • Wallpaper (if included)
   • Additional configs
6. Hyprotter will backup your current config and apply the theme

Managing Installed Themes

Go to Settings → Themes to see your installed themes. From here you can:

• Switch between installed themes
• Delete themes you no longer want
• Create a new theme from your current config
• Export themes as files to share manually

Share Your Config

Have you created an awesome Hyprland setup? Share it with the community! Here's how to publish your configuration to the Theme Library.

Step 1: Create an Account

First, you need a Hyprotter account. Click "Share Configs" in the navigation bar to create one. You'll need:

• A unique username
• A valid email address
• A password (min. 8 characters)

Step 2: Prepare Your Theme

Before publishing, make sure your configuration is ready:

Required

• Working Config - Test that everything works properly
• Screenshots - At least one screenshot showing your desktop
• Title - A descriptive name for your theme
• Description - Explain what makes your theme special

Recommended

• Multiple Screenshots - Show different aspects (empty, with windows, different workspaces)
• Color Palette - List the main colors used
• Font Information - Which fonts are required
• Dependencies - Any additional packages needed

Step 3: Upload Your Theme

1. Log in to your Hyprotter account
2. Go to your Profile page
3. Click "Upload New Theme"
4. Fill in the theme information:
   Title: Tokyo Night Minimal
   Description: A clean, minimal setup inspired by...
   Tags: minimal, dark, tokyo-night
   Components: [x] Hyprland [x] Waybar [ ] Rofi
5. Upload your screenshots (PNG or JPG, max 5MB each)
6. Upload your config files:
   • hyprland.conf - Your Hyprland configuration
   • waybar/ - Waybar config folder (optional)
   • wallpaper.png - Your wallpaper (optional)
7. Click "Publish"

Step 4: Maintain Your Theme

After publishing:

• Respond to user comments and questions
• Update your theme when Hyprland has breaking changes
• Add more screenshots or improve the description based on feedback
• Mark which Hyprland versions your theme supports

Theme Guidelines

To keep the Library useful for everyone:

• No malicious code - Configs are reviewed before publication
• Working configs only - Test before publishing
• Original work - Don't upload others' work without permission
• Appropriate content - Keep wallpapers and themes family-friendly
• Clear licensing - Specify if your theme has any restrictions

Frequently Asked Questions