Skip to main content

​
Prerequisites

Before installing Config-Sway, ensure you have:
Config-Sway is designed for Arch Linux. The install.sh script uses pacman for package management. If you’re on another distribution, you’ll need to manually install the required packages using your package manager.

​
Required Software

  • Arch Linux (or Arch-based distribution)
  • Git (to clone the repository)
  • sudo privileges (for installing system packages)
  • rsync (installed automatically by the script)

​
System Requirements

  • A system capable of running Wayland compositors
  • GPU drivers with Wayland support
  • At least 2GB of free disk space for packages and configuration files

​
Installation Methods

The install.sh script handles everything: installing dependencies and applying your dotfiles.
1

Clone the repository

First, clone the Config-Sway repository to your local machine:
git clone <your-repo-url> config-sway
cd config-sway
2

Run the installation script

Make the script executable and run it:
chmod +x install.sh
./install.sh
The script will:
  • Install all required packages using pacman
  • Automatically run update.sh to apply your dotfiles
  • Create backups of your existing configuration
3

Verify the installation

Check that Sway and related tools are installed:
sway --version
waybar --version
rofi -version

​
Method 2: Manual Installation

If you prefer manual control or are not on Arch Linux, follow these steps:
1

Install required packages

On Arch Linux, install all dependencies:
sudo pacman -S sway swaybg waybar mako kitty rofi flameshot \
  network-manager-applet xdg-desktop-portal xdg-desktop-portal-wlr \
  xdg-desktop-portal-gtk grim rsync brightnessctl playerctl \
  blueman swaylock ranger lsd bat fastfetch mpc alsa-utils libnotify
For other distributions, install the equivalent packages using your package manager.
2

Clone the repository

git clone <your-repo-url> config-sway
cd config-sway
3

Apply the dotfiles

chmod +x update.sh
./update.sh

​
What Gets Installed

​
Core Packages

The install.sh script installs the following packages: 
sway          # Tiling Wayland compositor
swaybg        # Wallpaper utility for Sway
waybar        # Highly customizable status bar
mako          # Notification daemon for Wayland

​
Understanding install.sh

The installation script is straightforward and safe: 
#!/usr/bin/env bash
set -euo pipefail

# Fails immediately on errors, undefined variables, or pipe failures

PKGS=(
  sway swaybg waybar mako kitty rofi flameshot network-manager-applet
  xdg-desktop-portal xdg-desktop-portal-wlr xdg-desktop-portal-gtk grim
  rsync brightnessctl playerctl blueman swaylock
  ranger lsd bat fastfetch mpc alsa-utils libnotify
)

# Installs packages with pacman
sudo pacman -S --needed "${PKGS[@]}"

# Applies your dotfiles
./update.sh
The --needed flag prevents reinstallation of already-installed packages, making the script safe to run multiple times.

​
Applying Configuration with update.sh

The update.sh script synchronizes your dotfiles from the repository to your home directory.

​
What update.sh Does

1

Creates automatic backups

Before making any changes, update.sh backs up your existing configuration:
  • ~/.config → ~/.config.bak-YYYYMMDD-HHMMSS/
  • Home dotfiles → ~/home-dots.bak-YYYYMMDD-HHMMSS/
Backups can consume significant disk space. Clean up old backups periodically to free up space.
2

Syncs managed configuration files

The script uses rsync --delete to synchronize:
  • ./.config/ → ~/.config/ (only top-level directories managed by the repo)
  • ./home/ → ~/ (only first-level files managed by the repo)
Managed files are tracked in:
  • ~/.config/.config-sway-managed
  • ~/.home-dots-managed
3

Removes deleted files

If you’ve removed files from the repository, update.sh removes them from your system too—but only for files it manages. Your other configurations remain untouched.
4

Reloads services

After syncing, the script automatically:
  • Restarts xdg-desktop-portal and xdg-desktop-portal-wlr
  • Reloads Sway configuration (swaymsg reload)
  • Restarts Waybar

​
Running update.sh

./update.sh
Use --no-backup only if you’re certain you don’t need to revert changes. This is useful after you’ve verified that the configuration works correctly.

​
Repository Structure

Understand what gets synchronized to your system:
Repository PathSystem DestinationContents
./.config/~/.config/Sway, Waybar, Rofi, Kitty, Neovim configs
./home/~/Top-level dotfiles (e.g., .zshrc)
./.config/themes/<theme>/~/.config/themes/<theme>/Theme resources (colors, wallpapers, styles)

​
Configuration Files Included

  • Sway: Window manager configuration, keybindings, autostart
  • Waybar: Status bar configuration and styling
  • Rofi: Application launcher and custom menus
  • Kitty: Terminal emulator configuration
  • Mako: Notification daemon settings
  • Theme system: Unified theming for all components

​
Backups

​
Automatic Backups

By default, update.sh creates timestamped backups: 
~/.config.bak-20260305-143052/
~/home-dots.bak-20260305-143052/

​
Restoring from Backup

If you need to revert your configuration: 
# Remove current config
rm -rf ~/.config

# Restore from backup (replace timestamp with your backup)
cp -a ~/.config.bak-20260305-143052 ~/.config
Test your configuration after updates. If something breaks, restore from your backup before the next update.sh run (which creates a new backup).

​
Troubleshooting

​
Flameshot Not Working

If Flameshot screenshots fail under Wayland:
1

Verify portal configuration

Check that ~/.config/xdg-desktop-portal/sway-portals.conf exists and contains:
[preferred]
default=gtk
org.freedesktop.impl.portal.Screenshot=wlr
org.freedesktop.impl.portal.ScreenCast=wlr
2

Restart portal services

systemctl --user restart xdg-desktop-portal xdg-desktop-portal-wlr
3

Check Sway configuration

Verify your Sway config imports environment variables correctly and includes the floating rule for Flameshot.

​
rsync Missing

If you get an error about rsync: 
sudo pacman -S rsync
Then run ./update.sh again.

​
Permission Denied

If scripts aren’t executable: 
chmod +x install.sh update.sh

​
Sway Won’t Start

1

Check Sway logs

journalctl --user -u sway -b
2

Verify GPU drivers

Ensure your GPU drivers support Wayland:
# For NVIDIA (not recommended for Wayland)
lsmod | grep nvidia

# For AMD/Intel (recommended)
lsmod | grep -E '(amdgpu|i915)'
3

Test with default config

# Move your config temporarily
mv ~/.config/sway ~/.config/sway.backup

# Try starting Sway with default config
sway

​
Package Installation Fails

If pacman fails to install packages: 
# Update package database
sudo pacman -Sy

# Try installing packages individually to identify the problem
sudo pacman -S sway
sudo pacman -S waybar
# ... etc

​
Next Steps

Now that you’ve installed Config-Sway, learn how to use it:

Quick Start Guide

Get Sway running and learn essential keybindings to navigate your new desktop environment.

​
Environment Variables

For optimal Wayland compatibility, set these environment variables before starting Sway: 
export XDG_CURRENT_DESKTOP=sway
export XDG_SESSION_TYPE=wayland
export XDG_SESSION_DESKTOP=sway
export MOZ_ENABLE_WAYLAND=1
export QT_QPA_PLATFORM=wayland
export SDL_VIDEODRIVER=wayland
You can add these to ~/.config/environment.d/sway.conf (one per line, format: KEY=value) or to your shell profile.

Build docs developers (and LLMs) love

Get started for freeTalk to us