User Guide

1. Getting Started

Follow these steps to install Basalt Linux on your computer.

1. Download the ISO

   Get the latest release from the download page. The ISO is about 2.3 GB.

2. Verify the download

   Compare the SHA256 checksum of your downloaded file with the one on the download page to make sure the file is intact.

   $ sha256sum basalt-linux.iso

3. Create a bootable USB drive

   Use Rufus (Windows), BalenaEtcher (any operating system), or the dd command on Linux. A USB drive of at least 8 GB is required.

   $ sudo dd if=basalt-linux.iso of=/dev/sdX bs=4M status=progress

4. Boot from the USB drive

   Restart your computer and enter the boot menu (F12, F2, Esc, or Del during startup). Select your USB drive, then choose Basalt Linux from the GRUB menu.

5. Install with Calamares

   On the live desktop, double-click Install Basalt Linux. The installer guides you through language, location, keyboard layout, partitioning, and user account creation.

6. Reboot

   When installation finishes, reboot and remove the USB drive when prompted. Log in with the username and password you created.

2. First Boot

When you boot into Basalt Linux for the first time, the Welcome app launches automatically. It provides quick access to common tasks:

• System information — View your hardware details
• Update system — Check for and install available updates
• Install software — Browse and install additional applications
• Community links — Join the Basalt Linux community

The Welcome app can be reopened anytime from the application menu.

Desktop Overview

Basalt Linux uses the Xfce desktop environment with the Orchis theme and Papirus icons. The layout is familiar and intuitive:

• Top panel — Application menu, window list, system tray, and clock
• Application menu — Click the Basalt logo in the top-left to access all installed applications
• Workspaces — Switch between multiple workspaces with the workspace switcher on the panel
• Right-click — Right-click on the desktop for quick access to common actions

3. Software Management

Basalt Linux comes with the essentials pre-installed, and thousands more applications are available through the package manager.

Using APT (Command Line)

The apt command is the primary way to manage software on Basalt Linux:

$ sudo apt update

$ sudo apt install firefox-esr

$ sudo apt remove <package>

$ sudo apt upgrade

To search for a package, use:

$ apt search <keyword>

Using Synaptic (Graphical)

If you prefer a graphical interface, Synaptic Package Manager provides full package management without the terminal. If it is not already installed, add it with:

$ sudo apt install synaptic

You can then find it in the application menu under System or Settings.

Flatpak Support

Flatpak is pre-installed and configured. You can install Flatpak applications from Flathub or other remotes:

$ flatpak install flathub org.mozilla.firefox

$ flatpak run org.mozilla.firefox

Pre-installed Applications

4. System Settings

Common settings are a few clicks away from the application menu.

Network (Wi-Fi & Wired)

Click the network icon on the panel to connect to Wi-Fi or check your wired connection. For advanced options, open Network Connections from the application menu, or run nm-connection-editor in the terminal.

Display Settings

Open Display from the Settings menu to configure resolution, refresh rate, and multi-monitor arrangement.

Printers

Go to Settings → Printers to add and configure printers. Basalt Linux supports most common printer brands through CUPS.

Power Management

Configure power-saving options, screen timeout, and suspend behaviour from Settings → Power Manager.

User Accounts

Manage users and passwords from Settings → Users and Groups. You can add, remove, or modify user accounts.

5. Updates & Maintenance

Keeping your system up to date is important for security and stability.

Update from the Terminal

$ sudo apt update && sudo apt upgrade

Update from the Welcome App

The Welcome app includes a one-click option to check for and install updates — perfect if you prefer not to use the terminal.

System Backup

Basalt Linux includes Timeshift, a system backup and restore tool. Creating a snapshot before major system changes is recommended. Open Timeshift from the application menu to configure automatic or manual snapshots.

Disk Cleanup

To free up disk space, remove unnecessary packages and clear cached package files:

$ sudo apt autoremove

$ sudo apt autoclean

6. System Requirements

A USB drive of at least 8 GB is required for the installation media. Secure Boot is supported via shim-signed.

7. Getting Help

If you run into issues or have questions, these are the best places to get help:

• Wiki — Detailed installation guide, FAQ, and troubleshooting articles
• Discord server — Community support and real-time chat
• Known Issues — Reported issues and workarounds
• GitLab — Report bugs, request features, or contribute