Debian-Hyprland/PACKAGE_INSTALL_TROUBLESHOOTING.md

Package Installation Troubleshooting Guide

Recent Update (2025-12-13)

The install.sh script has been updated to:

• Skip plugins by default (optional, can install manually)
• Skip debug symbols by default (optional, can install manually)
• Focus on core packages only for initial installation
• Improve dependency resolution with apt-get install -f

Common Dependency Issues

Issue: Missing libhyprlang2

Error:

hypridle depends on libhyprlang2 (>= 0.6.4); however:
Package libhyprlang2 is not installed.

Cause: libhyprlang is not included in the current pre-built packages. It needs to be built or installed from Debian repositories.

Solution:

# Option 1: Install from Debian repositories
sudo apt-get install libhyprlang2

# Option 2: Build from source (fallback to source method in install.sh)

Issue: Missing libaquamarine8

Error:

hyprland depends on libaquamarine8 (>= 0.9.5); however:
Package libaquamarine8 is not installed.

Cause: Pre-built packages have libaquamarine9, not libaquamarine8. Version mismatch.

Solution:

# Check what's installed:
dpkg -l | grep aquamarine

# If you have libaquamarine9, it should work with newer hyprland
# If not, install aquamarine from packages:
sudo dpkg -i /mnt/nas/Projects/Jak/debian-pkg/build/debs/libaquamarine*.deb

Issue: libstdc++6 version too old

Error:

hyprland depends on libstdc++6 (>= 15); however:
Version of libstdc++6:amd64 on system is 14.2.0-19.

Cause: System C++ standard library is older than required.

Solution:

# Update your system (highest priority):
sudo apt-get update
sudo apt-get upgrade

# Or install g++ 15:
sudo apt-get install g++-15

Issue: libxkbcommon0 version too old

Error:

hyprland depends on libxkbcommon0 (>= 1.12.3); however:
Version of libxkbcommon0:amd64 on system is 1.7.0-2.

Cause: System xkbcommon library is older than required.

Solution:

# Update system packages:
sudo apt-get update
sudo apt-get upgrade libxkbcommon0

# Or build from source:
sudo apt-get build-dep libxkbcommon

Installation Workflow (Updated)

Step 1: Install Core Packages

cd ~/Projects/Jak/Debian-Hyprland
./install.sh
# Select YES to use pre-built packages
# Script will skip plugins and debug symbols automatically

What gets installed:

• Core libraries (hyprutils, hyprgraphics, hyprcursor, etc.)
• Main compositor (hyprland)
• Essential utilities (hypridle, hyprlock, etc.)
• Development files (-dev packages)

What is skipped (can install manually later):

• Hyprland plugins (9 optional plugins)
• Debug symbols (-dbgsym packages)

Step 2: Fix Missing Dependencies

If you encounter missing dependencies:

# Install missing system dependencies:
sudo apt-get install -f -y

# This will attempt to resolve any broken dependencies from Debian repos

Step 3: Install Optional Components

Install plugins (if desired):

sudo dpkg -i /mnt/nas/Projects/Jak/debian-pkg/build/debs/hyprland-plugin-*.deb

Install debug symbols (if desired):

sudo dpkg -i /mnt/nas/Projects/Jak/debian-pkg/build/debs/*-dbgsym*.deb

Dependency Resolution Strategy

The updated script uses a staged approach:

1. Install core packages (libraries and binaries)
2. Run apt-get install -f to resolve from Debian repos
3. Skip optional components (plugins, debug)
4. Provide manual install commands for optional packages

System Requirements

For successful installation, ensure:

Component	Minimum	Recommended
libstdc++6	14.2.0	15.x
libxkbcommon0	1.7.0	1.12.3+
Debian Release	Trixie	Trixie or newer

Upgrading System Libraries

If you have dependency version issues:

# Full system upgrade (safest approach)
sudo apt-get update
sudo apt-get upgrade

# Or targeted package upgrades
sudo apt-get install --only-upgrade libstdc++6
sudo apt-get install --only-upgrade libxkbcommon0

Manual Installation Without Script

If the script fails, install packages manually:

cd /mnt/nas/Projects/Jak/debian-pkg/build/debs

# Install only core .deb files (not plugins or debug):
for deb in *.deb; do
    if [[ "$deb" != *"-dbgsym"* ]] && [[ "$deb" != "hyprland-plugin"* ]]; then
        sudo dpkg -i "$deb"
    fi
done

# Fix dependencies:
sudo apt-get install -f -y

Known Issues

Issue: Plugins require hyprland to be installed first

Status: Fixed in updated script (plugins skipped) Solution: Install core packages first, then manually install plugins

Issue: Debug symbols require main package

Status: Fixed in updated script (dbgsym skipped) Solution: Install main packages first, then manually install -dbgsym

Issue: Some libraries missing from pre-built

Status: Partially fixed with apt-get install -f Solution: Keep system updated, use fallback to source build if needed

Fallback to Source Build

If package installation fails completely:

cd ~/Projects/Jak/Debian-Hyprland
./install.sh
# When prompted: Select NO to build from source instead
# Takes 1-2 hours but builds everything from scratch

Getting Help

1. Check Install-Logs directory:

   cat Install-Logs/01-Hyprland-Install-Scripts-*.log
   

2. Check package status:

   dpkg -l | grep hyprland
   apt-cache policy hyprland
   

3. Check system libraries:

   ldd /usr/bin/Hyprland
   dpkg -l | grep libstdc++6
   dpkg -l | grep libxkbcommon0
   

Summary

Core Changes (2025-12-13):

• ✅ Skip plugins by default (reduce dependency issues)
• ✅ Skip debug symbols by default (faster installation)
• ✅ Auto-fix missing Debian dependencies with apt-get install -f
• ✅ Provide manual commands for optional packages
• ✅ Better error handling and logging

Installation Time:

• Core packages: 5-10 minutes
• With plugins: +5 minutes
• With debug symbols: +10 minutes

Next Steps After Install:

# Verify installation:
hyprland --version
Hyprland --help

# Install plugins (optional):
sudo dpkg -i /mnt/nas/Projects/Jak/debian-pkg/build/debs/hyprland-plugin-*.deb

# Install debug symbols (optional):
sudo dpkg -i /mnt/nas/Projects/Jak/debian-pkg/build/debs/*-dbgsym*.deb

# Reboot to ensure all changes take effect:
sudo reboot