Upgrading Nitrux is easy. We even support two methods to achieve this: using a utility created explicitly for this purpose or Calamares—yes, you read that right.
In today’s tutorial, we’ll check how to do this.
Difficulty: ★☆☆☆☆
📜 Table of Contents
About Upgrades in Nitrux
Below is the information we’ve deemed important for users to understand about this distribution and its upgrade process.
- We aim to release new upgrade archives for the Nitrux Update Tool System during the first week of the month, usually the same week as the latest release. Sometimes, this period may extend for a couple more days. Either way, we will announce the availability of the update archive on our social media, chat groups, and the PSA section on this website.
- The update archives for the Nitrux Update Tool System and the utility only support updating from the previous release to the latest, i.e., 3.4.0 to 3.4.1 or 3.4.1 to 3.5.0, etcetera. To upgrade from an older installation, i.e., 3.4.0, to 3.5.0, see Upgrade using Live media (Calamares).
- 🔰 Information: Regarding the OTA archives, we delete the previous files whenever a new archive is uploaded. We do not maintain an online archive of these files or the ISOs.
- Users must manually run the Nitrux Update Tool System to check for updates.
- ⚠️ Important: There’s no background process (i.e., a daemon), and the utility doesn’t force updates (offline updates); users are responsible for keeping their installations up to date.
- The Nitrux Update Tool System does not update or modify files in the user’s home directory, such as the desktop configuration, during upgrades or rollbacks.
- ⚠️ Important: Users can run the following command to update the files in their home directory to the default versions, then log out and log back in. However, this will replace them, so keep that in mind.
rm -r ~/.config/crystal-dock && cp -R /etc/skel/.config/* ~/.config/ && cp -R /etc/skel/.crystal-dock-2 ~/ && ln -sv ~/.crystal-dock-2 ~/.config/crystal-dock
- ⚠️ Important: Users can run the following command to update the files in their home directory to the default versions, then log out and log back in. However, this will replace them, so keep that in mind.
- Likewise, the Nitrux Update Tool System does not create backups of the user’s home directory.
Upgrade using the Nitrux Update Tool System
The Nitrux Update Tool System is a simple, minimalistic update and rollback utility. It performs three steps:
- It creates a backup of the XFS partition using xfsdump and stores it locally.
- Then, it downloads an OTA-style archive and updates the system atomically.
- Rollbacks are handled offline and integrated into the Nitrux ecosystem through the Live session using xfsrestore.
See the commands below to use the Nitrux Update Tool System.
sudo nuts update
- It uses the specified media in the nuts-query to update the currently installed root and back up the current root directory and partition.
- 🔰 Information: Depending on various factors, such as system specifications and Internet connection speed. Other factors affecting completion time include connectivity to GitHub and SourceForge, or their mirrors.
sudo nuts rescue
- Restores the XFS root partition backup if an update is interrupted.
- 🔰 Information: The user can only use this operation during a Live session.
sudo nuts self-update
- Updates the Nitrux Update Tool System and the configuration file using the Git branch set in the configuration file.
- ⚠️ Important: It’s essential to always run
nuts self-updatebefore updating the distribution.
- ⚠️ Important: It’s essential to always run
Upgrade using Live media (Calamares)
Using an installer like Calamares to “update” a distribution doesn’t occur to most people. But we can do this by replacing only the old root partition with a new one. Think of it as having a directory with multiple files (abc.txt, abcd.txt, abcxyz.txt) and deleting only one file instead of the entire directory. Now you have abc123.txt, abcd.txt, and abcxyz.txt.
This procedure requires a separate root partition distinct from your user partitions. Most Linux distributions use a single partition that contains everything, making selective root replacement impossible. That’s why Nitrux uses a custom partition layout and emphasizes avoiding a single-partition layout during initial installation.
Some might mistake this for “reinstalling.” However, reinstalling means reusing the original installation media. If you originally installed Nitrux 2.9.0, reinstalling will still keep you at 2.9.0. What we’re describing is different: you boot Nitrux 2.9.1 media, delete the 2.9.0 root partition, and install a fresh 2.9.1 root while keeping your other partitions intact.
To upgrade from previous versions of Nitrux using Calamares, do the following:
- Download and flash the latest ISO.
- Boot to the Live session and start Calamares.
- After completing the locale, keyboard, and user configuration, select “Manual partitioning.”
- Select and delete the previous installation root; do not delete or format other partitions unless desired; only select “Keep.”
- 🔰 Information: For further details about manual partitioning, see Getting Started → Installation Guide → Install Nitrux → Non-automated Partitioning Options.
The table below defines our partition layout for EFI/UEFI-based computers with GPT (GUID Partition Table) storage devices.
- ⚠️ Important: Please be aware that the root directory is immutable, and any directory within the root will be read-only. Do not use a single partition layout.
| Partition | Label | Mountpoint | Filesystem Type | Flags |
|---|---|---|---|---|
| EFI System Partition | ESP | /boot/efi | fat32 | boot |
| root | NX_ROOT | / | xfs | none |
| home | NX_HOME | /home | f2fs | none |
| /var/lib | NX_VAR_LIB | /var/lib | f2fs | none |
| swap | SWAP | none (automatically set up) | linuxswap | swap |
Finally, proceed with installing the new root.
- 🔰 Information: Replacing the root does not update or modify files in the user’s home directory, such as the desktop configuration.
- ⚠️ Important: Users can run the command to update the files in their home directory to the default versions, then log out and back in. However, this will replace them, so keep that in mind.
rm -r ~/.config/crystal-dock && cp -R /etc/skel/.config/* ~/.config/ && cp -R /etc/skel/.crystal-dock-2 ~/ && ln -sv ~/.crystal-dock-2 ~/.config/crystal-dock
- ⚠️ Important: Users can run the command to update the files in their home directory to the default versions, then log out and back in. However, this will replace them, so keep that in mind.
Troubleshooting
Below is the information we deem necessary for users to troubleshoot problems.
Unable to Find an Overlay Filesystem Error
When using the Nitrux Update Tool System, the error message ERROR: Unable to find an overlayroot filesystem will appear after the following user actions:
- Turning off the overlay functionality by editing the boot parameter and booting the distribution afterward.
- Using the command
sudo overlayroot-chrootand attempting to execute the commandsudo nuts <option>within the shell session afterward.
The error message indicates that OverlayFS is not in use. As detailed on our website, this distribution uses OverlayFS. Doing either of these actions will prevent the Nitrux Upgrade Tool System from functioning.
We strongly recommend following the straightforward instructions in this tutorial. This problem is not a bug or issue with Nitrux or the Nitrux Update Tool System.
Unable to Resolve Partition Label
When using the Nitrux Update Tool System, the error message findfs: unable to resolve LABEL will be displayed if the user does not install the distribution following our specific instructions, as outlined in this tutorial.
The error message indicates that the specified partition lacks a label. This distribution specifies partition labels during installation precisely because we require them for our update process. This problem is not a bug or issue with Nitrux or the Nitrux Update Tool System.
Unable to Create Redundant Backup of Root Partition
If the user did not use the XFS filesystem for the root partition, the Nitrux Update Tool System will not be able to create a redundant backup of the root partition, which means that using the command nuts rescue will not work.
As we mentioned in Installing Nitrux and this tutorial, we’ve designed our distribution with XFS and F2FS in mind, and no other filesystems. This problem is not a bug or issue with Nitrux or the Nitrux Update Tool System.
Unable to Access GitHub
If your computer can’t reach the domain raw.githubusercontent.com, you cannot proceed with the update process. We recommend using a VPN or a proxy, or contacting your ISP if they block access to these domains.
Update Failed due to External Factors (Power Outage, Hardware Failure, etc.)
In the event that the Nitrux Update Tool System is unable to apply an update due to an external factor, the built-in method is to execute sudo nuts rescue to restore the XFS backup, which restores the integrity of the system.
Report Update Process Bugs
To report problems with the Nitrux Update Tool System during the update, please use our bug tracker on GitHub and include the file /var/log/nuts.log in a bug report.
- 🔰 Information: This file is only available during the active session.
That’s it; this concludes today’s tutorial.