Skip to main content

​
Installation Guide

This guide will walk you through the complete installation process for Kanagawa dotfiles on your Arch Linux system.
Backup Your Configurations! Before proceeding, make sure to backup your existing dotfiles and configurations. This installation will create symlinks that may override existing files.

​
Prerequisites

1

Arch Linux Installation

You must be running Arch Linux (or an Arch-based distribution). This configuration is specifically designed for Arch.Verify your system:
cat /etc/os-release | grep "Arch Linux"
2

Required Packages

Install the essential packages needed for this configuration:
sudo pacman -S hyprland waybar wofi ghostty \
               swaync wlogout hyprpaper \
               polkit-gnome xdg-desktop-portal-hyprland
GNU Stow is essential for this installation. It manages symlinks from the dotfiles repository to your system configuration directories.
3

Shell Setup

If you haven’t already, change your shell to Zsh:
chsh -s $(which zsh)
Install Oh My Zsh and Powerlevel10k:
# Install Oh My Zsh
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

# Install Powerlevel10k theme
git clone --depth=1 https://github.com/romkatv/powerlevel10k.git \
  ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

​
Installation Process

1

Clone the Repository

Clone the Kanagawa dotfiles repository to your home directory:
git clone https://github.com/nixer112/dotfiles.git ~/dotfiles
cd ~/dotfiles
The repository should be cloned to ~/dotfiles as the scripts expect this location.
2

Review the Installation Script

Before running the installer, let’s understand what it does. Here’s the complete install.sh script:
#!/bin/bash

# Colores para la terminal
GREEN='\033[0;32m'
NC='\033[0m'

echo -e "${GREEN}Iniciando instalación de dotfiles... ${NC}"

# Crear carpeta .config si no existe
mkdir -p ~/.config
mkdir -p ~/.local/bin

# stow -v (verbose) -R (recursive) -t (target)
# Linkeamos lo que hay dentro de la carpeta 'config' a ~/.config
stow -v -R -t ~/.config config
stow -v -R -t ~/.local/bin scripts

# Linkeamos lo que hay en 'shell' al HOME
stow -v -R -t ~ shell

echo -e "${GREEN}¡Todo listo! Enlaces creados.${NC}"
What it does:
  • Creates ~/.config and ~/.local/bin directories if they don’t exist
  • Uses stow -R (restow) to create/update symlinks
  • Links config/ directory contents to ~/.config/
  • Links scripts/ directory contents to ~/.local/bin/
  • Links shell/ directory contents to your home directory (~)
The -R flag means “restow”, which first unstows and then stows again. This is safe to run multiple times.
3

Run the Installation Script

Make the script executable and run it:
chmod +x install.sh
./install.sh
You should see output like:
Iniciando instalación de dotfiles...
LINK: .zshrc => dotfiles/shell/.zshrc
LINK: .config/hypr => dotfiles/config/hypr
LINK: .config/waybar => dotfiles/config/waybar
...
¡Todo listo! Enlaces creados.
4

Make Scripts Executable

Ensure all scripts in ~/.local/bin are executable:
chmod +x ~/.local/bin/*
Verify the theme scripts are accessible:
which theme-selector
which theme-switcher

​
Post-Installation Steps

1

Reload Your Shell

Start a new shell session or reload your configuration:
exec zsh
Powerlevel10k will prompt you to configure it on first launch. Follow the interactive setup wizard.
2

Start Hyprland

If you’re not already in Hyprland, start it:
Hyprland
Or reboot and select Hyprland from your display manager.
3

Test the Theme Selector

Once in Hyprland, test the theme switcher:
theme-selector
This will launch a Wofi menu where you can choose from:
  • Kanagawa (default)
  • Gruvbox
  • Catppuccin
  • Everforest
The theme selector will automatically update all configured applications including Hyprland, Waybar, Wofi, Ghostty, Neovim, VSCodium, SwayNC, and more.
4

Verify All Components

Check that all components are working:
Should appear at the top of your screen. If not:
waybar &
Press Super + D (or your configured keybind) to open the application launcher.
Press Super + Return to open a terminal. Check that the Kanagawa theme is applied.
Test notifications:
notify-send "Test" "Kanagawa dotfiles are working!"

​
Configuration Locations

After installation, your configurations will be symlinked to these locations:
ComponentSymlink LocationSource
Hyprland~/.config/hypr/~/dotfiles/config/hypr/
Waybar~/.config/waybar/~/dotfiles/config/waybar/
Ghostty~/.config/ghostty/~/dotfiles/config/ghostty/
Wofi~/.config/wofi/~/dotfiles/config/wofi/
Neovim~/.config/nvim/~/dotfiles/config/nvim/
SwayNC~/.config/swaync/~/dotfiles/config/swaync/
Wlogout~/.config/wlogout/~/dotfiles/config/wlogout/
Btop~/.config/btop/~/dotfiles/config/btop/
Cava~/.config/cava/~/dotfiles/config/cava/
Scripts~/.local/bin/~/dotfiles/scripts/
Zsh~/.zshrc~/dotfiles/shell/.zshrc
To modify any configuration, edit the files in ~/dotfiles/ and the changes will be reflected immediately through the symlinks.

​
Troubleshooting

If you get errors about existing files:
# Backup your existing configs
mkdir -p ~/backup-configs
mv ~/.config/hypr ~/backup-configs/
mv ~/.config/waybar ~/backup-configs/
# ... backup other conflicting directories

# Then run install.sh again
./install.sh
Ensure ~/.local/bin is in your PATH:
echo $PATH | grep ".local/bin"
If not, add this to your ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
Manually start Waybar:
killall waybar
waybar &
Check Hyprland config for autostart:
grep waybar ~/.config/hypr/hyprland.conf
Verify all theme files exist:
ls ~/.config/hypr/colors/custom/
ls ~/.config/waybar/colors/custom/
ls ~/.config/wofi/colors/custom/
Run theme-switcher directly:
theme-switcher kanagawa

​
Uninstallation

If you need to remove the dotfiles: 
cd ~/dotfiles
stow -D -t ~/.config config
stow -D -t ~/.local/bin scripts
stow -D -t ~ shell
This will remove all symlinks created by the installation.

​
Next Steps

Quick Start Guide

Learn the essential commands and workflows

Configuration

Customize your setup to your preferences

Keybindings

Master the keyboard shortcuts

Themes

Explore and customize themes

Build docs developers (and LLMs) love

Get started for freeTalk to us