Skip to content
ArchEclipse

Common pages

↑↓to navigate↵to openescto close
Installation
On this page

Getting Started

Installation

Run the installer, understand every step, choose a branch, update safely and uninstall ArchEclipse.

The installer is a Python entrypoint at .config/hypr/maintenance/install.py. It bootstraps its own prerequisites, clones the repository, and then runs a plan of optional components. This page describes what each part does so you can decide what to accept.

Prerequisites in detail#

  1. Arch Linux with a working graphical stack. The repository targets Arch; other Arch-based systems are not tested upstream.
  2. Hyprland installed and working. ArchEclipse installs hyprland from the package list, but does not install or configure your GPU drivers. Verify a plain Hyprland session starts before continuing.
  3. Python 3. The installer is run with python3.
  4. sudo access. Packages, greetd configuration and system tweaks require it.
  5. An AUR helper or the ability to build one. If yay and paru are both missing, the installer clones and builds the helper you select.

Run the installer#

bash
python3 <(curl -fsSL https://raw.githubusercontent.com/AymanLyesri/ArchEclipse/refs/heads/master/.config/hypr/maintenance/install.py)

The script prints an installation plan and asks which steps to run. Defaults are shown in brackets; pressing Enter accepts the default.

Installer steps#

StepDefaultWhat happens
Back up old dotfilesnoCopies tracked entries that already exist in ~ into ~/dotfiles_backup_<date> before deployment.
Apply ArchEclipse configurationyesSets a git worktree at $HOME and force-checks out tracked files.
Keyboard configurationnoOptional keyboard setup component.
LocalenoAdds en_US.UTF-8 if it is missing.
Remove unwanted packagesnoRemoves dunst and swaync if installed (Quickshell owns notifications).
Install necessary packagesyesInstalls the embedded package list with your chosen AUR helper.
Greetd + Quickshell greeteryesConfigures the greetd login screen and syncs the greeter theme.
Default configurationsyesCopies config/defaults/* into config/custom/ only when the target does not exist.
BrowseryesLets you pick a browser and generates config/custom/browser.lua.
Discord clientyesLets you pick a client and generates config/custom/discord_client.lua.
WallpapersyesDownloads the default wallpaper categories.
PluginsyesInstalls Hyprland plugins with hyprpm.
System tweaksyesMasks NetworkManager-wait-online.service to shorten boot.

The plan is collected before anything runs. The installer then executes the selected steps without further prompts, apart from package manager interaction.

Browser and Discord choices#

The browser step offers helium-browser (recommended), zen-browser, firefox, chromium and google-chrome. The Discord step offers legcord (recommended), discord, betterdiscord and vesktop. Each choice rewrites a small Lua module in ~/.config/hypr/config/custom/, which starts the app and places its window on a workspace.

After the installer#

The script reloads Hyprland and prints a completion message. Package changes, the greetd configuration and user services still need a reboot or a fresh login. Reboot, then follow First Boot.

Choosing a branch#

The installer accepts a branch in three ways, in this order of precedence:

bash
# 1. Explicit flag
python3 install.py --branch dev

# 2. Environment variable
ARCHECLIPSE_BRANCH=dev python3 install.py

# 3. Legacy positional argument
python3 install.py dev

Without any of these it installs master. The checkout is shallow (--depth 1 --single-branch) and is reset to the fetched branch.

Updating#

Use the Zsh function:

bash
archeclipse

or run the local updater:

bash
python3 ~/.config/hypr/maintenance/update.py

The updater:

  1. Verifies that ~ is still a valid ArchEclipse checkout and repairs it with a fresh clone if git history is missing or corrupt.
  2. Fetches the branch and runs git reset --hard plus a checkout.
  3. Reinstalls/updates the package list with yay or paru when available.
  4. Reloads the bar, updates plugins and optionally reconfigures the greeter.

Uninstalling#

The local uninstaller removes tracked ArchEclipse paths from $HOME, optionally restores the latest dotfiles_backup_*, and can remove packages from the project list (protected packages are kept).

bash
python3 ~/.config/hypr/maintenance/uninstall.py

Useful flags:

FlagEffect
--yesSkip prompts; keeps packages unless --remove-packages is given.
--backup / --no-backupCreate a temporary recovery copy in /tmp, or skip it.
--remove-packages / --keep-packagesDecide whether installed project packages are offered for removal.
--remove-pluginsRemove Hyprland plugin repositories configured by ArchEclipse.
--reset-shellSwitch the login shell back to Bash and remove ~/.zshrc.
--no-restoreDo not restore the latest installation backup.

The uninstaller refuses to run as root. It creates a safety copy only when asked, then removes the tracked paths, restores a previous dotfiles backup when one exists, and finally removes ~/ArchEclipse.