🪟 i3-setup

🚨 REPOSITORY MIGRATION NOTICE

This repository has moved to Codeberg

• Primary repository: https://codeberg.org/justaguylinux/i3-setup
• This GitHub repository: Mirror only (read-only)
• Migration deadline: December 15, 2025 - GitHub mirror will be archived

Please update your bookmarks and git remotes:

git remote set-url origin https://codeberg.org/justaguylinux/i3-setup.git

A minimal but functional i3 rice script for Debian-based systems. Installs all core packages, window manager configs, and themes — ready to go out of the box.

Part of the JustAGuy Linux window manager collection.

git clone https://codeberg.org/justaguylinux/i3-setup.git
cd i3-setup
chmod +x install.sh
./install.sh

The installer supports the following options:

./install.sh [OPTIONS]

Options:
  --only-config      Only copy config files (skip packages and external tools)
  --export-packages  Export package lists for different distros and exit
  --help             Show help message

New Features:

• Export packages: Use --export-packages to see equivalent package lists for Arch Linux and Fedora
• Streamlined installation: Simpler, more reliable installation process
• Better error handling: Installation fails fast on errors to prevent partial setups

Package Installation: Packages are installed in logical groups (core, UI, file manager, audio, utilities, terminal, fonts) for better organization.

# Install dependencies (package names may differ)
sudo pacman -S i3 sxhkd polybar rofi dunst picom thunar \
  xorg-xbacklight pamixer pavucontrol feh flameshot firefox \
  network-manager-applet xfce4-power-manager ttf-font-awesome

# Copy configuration files
./install.sh --only-config

# Install dependencies (package names may differ)
sudo dnf install i3 sxhkd polybar rofi dunst picom thunar \
  xbacklight pamixer pavucontrol feh flameshot firefox \
  network-manager-applet xfce4-power-manager fontawesome-fonts

# Copy configuration files
./install.sh --only-config

# Install dependencies (package names may differ)
sudo zypper install i3 sxhkd polybar rofi dunst picom thunar \
  xbacklight pamixer pavucontrol feh flameshot firefox \
  NetworkManager-applet xfce4-power-manager fontawesome-fonts

# Copy configuration files
./install.sh --only-config

# Export package lists for other distributions
./install.sh --export-packages

# Update only configuration files (useful for non-Debian systems)
./install.sh --only-config

Note: The script can be run from any location - it automatically detects its directory.

Optional during install:

• geany + plugins - Lightweight IDE (installer will prompt)

📄 Need help with Geany? See the full guide at justaguylinux.com/documentation/software/geany

• Minimal theme with custom wallpapers
• Polybar with optimized layout: system info (left), workspaces (center), controls (right)
• Enhanced polybar with multiple font support (Roboto Mono, FontAwesome, Hack Nerd Font)
• Dunst, rofi, and GTK themes preconfigured
• Wallpapers stored in ~/.config/i3/wallpaper
• GTK Theme: Orchis
• Icon Theme: Colloid

💡 Special thanks to vinceliuice for the excellent GTK and icon themes.

Keybindings are configured via:

• ~/.config/i3/sxhkd/sxhkdrc
• ~/.config/i3/scripts/help (run manually or with Super + H)

~/.config/i3/
├── config                 # Main i3 config
├── workspaces.conf        # Workspace definitions
├── rules.conf             # Window rules and appearance
├── sxhkd/
│   └── sxhkdrc            # Keybinding configuration
├── polybar/
│   ├── config.ini
│   └── polybar-i3
├── dunst/
│   └── dunstrc
├── rofi/
│   ├── config.rasi
│   ├── keybinds.rasi
│   └── power.rasi
├── picom/
│   └── picom.conf
├── scripts/
│   ├── autostart.sh
│   ├── changevolume
│   ├── power
│   ├── scratchpad
│   └── help
├── wallpaper/
│   └── (wallpaper images)

The setup uses two terminals for different purposes:

• Main terminal (Super + Enter): Uses wezterm by default
• Scratchpad terminal (Super + Shift + Enter): Enhanced auto-detection with comprehensive fallback support

The scratchpad system now supports multiple terminal emulators with intelligent fallback:

Supported terminals: st, ghostty, alacritty, kitty, wezterm, xfce4-terminal, gnome-terminal, konsole, urxvt

Priority order:

1. User-defined via I3_SCRATCHPAD_TERMINAL environment variable
2. st (preferred for speed and minimal resource usage)
3. Automatic fallback through available terminals

To customize the scratchpad terminal, set the environment variable in your shell config:

export I3_SCRATCHPAD_TERMINAL=ghostty  # or any terminal you prefer

Advanced scratchpad usage:

# Launch custom applications in scratchpad mode
Super + Shift + Enter    # Default terminal scratchpad
Super + V                # Pulsemixer scratchpad
# Or via script: scratchpad app_name app_command

This i3 setup uses a modular configuration approach for better organization:

• config: Main i3 configuration with includes
• workspaces.conf: Workspace definitions (1-10)
• rules.conf: Window rules, borders, gaps, and scratchpad settings
• sxhkd/sxhkdrc: All keybindings managed by sxhkd for consistency

This modular approach makes it easy to:

• Understand and modify specific aspects of the configuration
• Share configurations between different window managers
• Keep the main config file clean and focused

If this setup has been helpful, consider buying me a coffee:

Want to see how it looks and works?
🎥 Check out JustAGuy Linux on YouTube