JavaScript enables search, bookmarks and copying. All reference content remains available below.
Everyday essentials
The commands worth keeping close. Start here when checking a machine or refreshing packages.
Identify this installation
Check the distribution, running kernel and display session before following version-specific instructions.
cat /etc/os-release
uname -r
printf "%s\n" "$XDG_SESSION_TYPE"
xfce4-session --version
Refresh package lists
Run once before installing packages. This refreshes the package index; it does not upgrade installed software.
sudo apt update
Review and install updates
Review the proposed changes. Save work and restart afterward if the system requests it.
apt list --upgradable
sudo apt upgrade
Inspect disks and free space
Read-only checks for filesystem types, UUIDs, mount points and available space.
lsblk -o NAME,SIZE,FSTYPE,LABEL,UUID,MOUNTPOINTS
df -hT
Inspect graphics and USB devices
Requires pciutils and usbutils from Dependencies → Hardware utilities.
lspci | grep -Ei 'VGA|3D|Display|NVIDIA'
lsusb
Restart the laptop
Save your work and stop running inspections first.
sudo reboot
Create an administrator
Replace inspection-admin with your chosen username. Keep normal sudo password prompts enabled.
sudo adduser inspection-admin
sudo usermod -aG sudo inspection-admin
id inspection-admin
Change your password
Changes the password for the current account.
passwd
Optional SSH access
Install only if you want remote terminal access. Confirm your firewall and network access policy before connecting.
sudo apt install openssh-server
sudo systemctl enable --now ssh
systemctl status ssh --no-pager
Tools & archives
Install useful everyday utilities: compression and archive support, system monitoring, file search and network checks. Pick the groups you need; these are separate from Singularity prerequisites.
Install the complete archive toolkit
Refresh package lists with sudo apt update, then install this group for ZIP, 7z, RAR extraction, tar, gzip, bzip2, xz, Zstandard, LZ4, lzip, lzop, legacy .Z, CAB, ARJ and LHA/LZH archives. Xarchiver and the Thunar plugin add graphical archive handling in Xfce.
sudo apt install zip unzip 7zip 7zip-rar unrar unar tar gzip bzip2 xz-utils zstd lz4 lzip lzop ncompress pigz pbzip2 cpio cabextract arj lhasa xarchiver thunar-archive-plugin
For Ubuntu/Xubuntu 24.04 and newer. Universe and Multiverse must be enabled; use the repository step below if packages cannot be located. 7zip-rar adds RAR reading to 7-Zip; unrar extracts RAR but does not create it. This covers common formats, not every archive format ever made. You can keep File Roller installed alongside Xarchiver.
Ubuntu Xarchiver package and supported helpers
Ubuntu 7-Zip RAR plugin
If Ubuntu cannot find the archive packages
On Ubuntu/Xubuntu, enable the official Universe and Multiverse components, refresh the package lists, then repeat the archive install command. Skip this if those repositories are already enabled.
sudo apt install software-properties-common &&
sudo add-apt-repository universe &&
sudo add-apt-repository multiverse &&
sudo apt update
These repository commands are for Ubuntu/Xubuntu, not Debian. Use packages for your installed release. Ubuntu 22.04 uses the older p7zip-full and p7zip-rar names; do not add a newer Ubuntu release repository just to obtain 7zip.
Use archives from Thunar
After installation, right-click an archive in Thunar and choose Extract Here or Extract To. Select files or a folder and choose Create Archive to compress them. Xarchiver can also be opened from the Applications menu.
xarchiver
If the archive actions do not appear, close and reopen Thunar or log out and back in. The helper for the selected format must be installed.
Create, inspect and extract a ZIP
Replace ExampleFolder and example.zip with your paths. The extraction command places the contents in a separate folder.
zip -r example.zip ExampleFolder/
unzip -l example.zip
unzip example.zip -d extracted-zip
Create, inspect and extract a 7z archive
The current 7zip package provides 7zz. These commands create a 7z archive, list its contents and extract it with directories preserved.
7zz a example.7z ExampleFolder/
7zz l example.7z
7zz x example.7z -oextracted-7z
For an older p7zip installation, use 7z instead of 7zz. The -o output-folder option has no space after it.
Inspect and extract a RAR archive
Use unrar for RAR extraction. x preserves the directory structure. Keep all parts of a multipart archive in the same folder and extract the first part.
unrar l example.rar
mkdir -p extracted-rar &&
unrar x example.rar extracted-rar/
Create and extract a tar.gz archive
A tar archive preserves a directory tree; gzip compresses it. Extract into a separate directory so the contents are easy to find.
tar -czf example.tar.gz ExampleFolder/
tar -tzf example.tar.gz
mkdir -p extracted-tar &&
tar -xzf example.tar.gz -C extracted-tar
For tar.xz use -cJf / -tJf / -xJf. For tar.bz2 use -cjf / -tjf / -xjf. Run extraction as your normal user.
Use multiple CPU cores for compression
pigz compresses gzip streams with multiple threads. This example produces a normal tar.gz archive that standard tar tools can extract.
tar -I pigz -cf example.tar.gz ExampleFolder/
pbzip2 is the parallel bzip2 helper. For a single file, pigz -k filename keeps the original while writing filename.gz.
Install system monitors
Useful tools for CPU/memory/process inspection, disk-usage browsing and checking which process has a file open.
sudo apt install htop btop ncdu lsof procps psmisc sysstat
Use htop or btop for a live overview; ncdu browses folder sizes. These tools are optional and are not Singularity runtime dependencies.
Check resource use and free space
These checks report memory, disk space and the processes using the most CPU. Run htop or btop for an interactive view.
free -h
df -h
ps -eo pid,comm,%cpu,%mem --sort=-%cpu | head -n 16
ncdu "$HOME"
ncdu includes deletion controls; browse without deleting anything you want to keep.
Install file and search utilities
rsync copies/synchronizes files, tree shows folders, ripgrep searches text, fd-find finds files, jq reads JSON, dos2unix repairs text line endings, and wget/curl download files.
sudo apt install rsync tree ripgrep fd-find jq dos2unix wget curl
The Ubuntu fd-find executable is named fdfind. Keep your original file before converting line endings or replacing it.
Find files, search text and inspect JSON
Replace the example paths. These commands list files, search logs and print JSON without modifying it.
tree -L 2 ExampleFolder/
fdfind -e log . ExampleFolder/
rg -n -i "error|failed" ExampleFolder/
jq . settings.json
Install network diagnostics
Basic connectivity, DNS, route and network-interface checks. These commands install diagnostic utilities without changing network configuration.
sudo apt install iproute2 iputils-ping dnsutils traceroute mtr-tiny ethtool
ping, DNS and route checks contact the named destination. Use your own host or a destination you intend to troubleshoot.
Check interfaces, DNS and connectivity
View local addresses/routes/listening sockets, then test a destination. Replace example.com with your server or domain.
ip -br address
ip route
ss -tuln
ping -c 4 example.com
dig example.com
traceroute example.com
Desktop applications and hardware utilities
The existing desktop-app installation command still includes the editor, remote desktop client, media player, calculator and File Roller. The original dependency groups, hardware utilities, full Xfce setup and Xorg-only kiosk guide remain available.
Useful desktop tools
USB, PCI and camera utilities
All dependency groups
Dependencies
Choose the dependency groups you need, or combine them into one command using the builder. The complete Singularity prerequisite command is at the end; it can be used on its own.
Build tools
Shared compiler and build tooling. Install once; Python, wxPython and VMware instructions refer back here.
sudo apt install build-essential git pkg-config cmake ninja-build curl ca-certificates xz-utils
System Python development
Use the Ubuntu-provided Python and virtual environments. Custom Python source builds use the additional group below.
sudo apt install python3-dev python3-venv python3-tk
Native graphics runtime
OpenGL, X11 and OpenMP libraries for native UI and vision packages.
sudo apt install libstdc++6 libgl1 libglu1-mesa libegl1 libgomp1 libx11-6 libxext6 libxfixes3 libxrandr2 libxcb1 libxcb-randr0 libxcb-render0 libxcb-shm0 libxcb-xfixes0 libsm6 libice6
Build Python from source
Optional development headers for SSL, SQLite, Tk, compression and standard-library modules. Use libncurses-dev instead of the older versioned package name.
sudo apt install libsqlite3-dev tk-dev tcl-dev libssl-dev zlib1g-dev libffi-dev libbz2-dev libreadline-dev libncurses-dev liblzma-dev uuid-dev libgdbm-dev libgdbm-compat-dev libzstd-dev
CPython build prerequisites
Build wxPython from source
Only needed when installing a source distribution rather than a compatible wheel. Also select Build tools and System Python development, or use your custom interpreter headers.
sudo apt install libgtk-3-dev libgl1-mesa-dev libglu1-mesa-dev libsdl2-dev
Hardware utilities
Inspect USB/PCI devices, cameras and network interfaces.
sudo apt install libusb-1.0-0 usbutils pciutils ethtool iproute2 v4l-utils
Database runtime
Optional: use when your application actually needs ODBC or PostgreSQL client libraries.
sudo apt install unixodbc libpq5
Install Singularity dependencies
Refresh APT with sudo apt update, then run this one command on Ubuntu/Xubuntu 22.04 or newer or Debian 12/13. It includes the build dependencies needed by the installer and the native runtime libraries for 2D, 3D and database support. APT installs their supporting dependencies automatically.
sudo apt install bash build-essential binutils pkg-config linux-libc-dev curl ca-certificates tar gzip findutils gawk sed grep diffutils coreutils libc-bin util-linux libgtk-3-dev libgl1-mesa-dev libglu1-mesa-dev libsdl2-dev libstdc++6 libgomp1 libgl1 libglu1-mesa libx11-6 libxext6 libxfixes3 libxrandr2 libxcb1 libxcb-randr0 libxcb-render0 libxcb-shm0 libxcb-xfixes0 libegl1 libusb-1.0-0 libidn2-0 unixodbc libodbc2 unzip libnotify4 libjpeg-turbo8 libtiff6
This does not install XFCE, Xorg, Wayland, XWayland or hardware/vendor drivers. The X11/XCB and OpenGL packages here are client libraries required to load the application, not a desktop or display server. install.sh supplies private Python and the selected Python packages. You do not need the separate system-Python development, Python-source-build or hardware-utility groups for a normal Singularity installation. Polkit/desktop authentication-agent setup is separate if you need machine-wide license installation from the UI.
Singularity installation guide
Python & environments
Prefer a virtual environment. Keep custom GIL and free-threaded interpreters separate from Ubuntu’s system Python.
Create a project environment
Install the System Python development dependency group first. Run these in your project folder. Reactivate the environment in each new terminal.
python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip --version
Install headless OpenCV
Inside your activated environment. Appropriate when the application supplies its own UI and does not use cv2.imshow. Follow your application’s pinned requirements when provided.
python -m pip install opencv-python-headless
python -c "import cv2; print(cv2.__version__)"
Choose one OpenCV distribution per environment; do not mix opencv-python, opencv-python-headless and contrib variants.
Check standard-library support
Run with the interpreter you will actually use. The Tkinter command opens a test window in a desktop session.
python -c "import ssl, sqlite3, bz2, lzma, ctypes, tkinter; print(ssl.OPENSSL_VERSION); print(sqlite3.sqlite_version)"
python -m tkinter
Optional: get a pinned CPython source
The old guide pinned 3.14.3. This remains a reproducible example, not a claim that it is the latest patch. Select the patch supported by your compiled packages and verify the download using python.org release information.
Optional
mkdir -p ~/src
cd ~/src
curl -fLO https://www.python.org/ftp/python/3.14.3/Python-3.14.3.tar.xz
tar -xf Python-3.14.3.tar.xz
Python releases
Configure options
Build the standard interpreter
Install Build tools and Build Python from source first. Use a separate build directory. altinstall avoids replacing system python3.
Optional
mkdir -p ~/src/build-python-3.14.3-gil
cd ~/src/build-python-3.14.3-gil
../Python-3.14.3/configure --enable-optimizations --with-lto --prefix=/opt/python/gil
make -j"$(nproc)"
sudo make altinstall
/opt/python/gil/bin/python3.14 -m venv ~/venvs/singularity-gil
Build a separate free-threaded interpreter
Use a clean, separate build directory. Native extensions need compatible free-threaded builds; do not assume standard ABI wheels will work.
Optional
mkdir -p ~/src/build-python-3.14.3-nogil
cd ~/src/build-python-3.14.3-nogil
../Python-3.14.3/configure --disable-gil --enable-optimizations --with-lto --prefix=/opt/python/nogil
make -j"$(nproc)"
sudo make altinstall
/opt/python/nogil/bin/python3.14t -m venv ~/venvs/singularity-nogil
Free-threaded Python compatibility
Run and check a free-threaded environment
Replace File.py with your script. Run as your normal desktop user. Some extensions re-enable the GIL or require specific builds.
source ~/venvs/singularity-nogil/bin/activate
python -c "import sys, sysconfig; print(sys.version); print(sysconfig.get_config_var('Py_GIL_DISABLED')); print(sys._is_gil_enabled())"
python -X gil=0 File.py
Leave the virtual environment
Returns this terminal to its previous Python PATH.
deactivate
Full Xfce desktop
Path 1: install a full Xfce desktop from an SSH-only Ubuntu system, including Xorg, the desktop session, panel, file manager, utilities and graphical login. For an app-only system, use the separate Xorg-only kiosk guide.
Path 1: full Xfce desktop from SSH
Follow the numbered steps on the Ubuntu machine you connect to over SSH, using your normal account with sudo. This installs the desktop for its attached monitor or VM console.
SSH remains a terminal connection. Installing Xfce does not automatically provide remote desktop viewing; a headless machine needs separately configured remote-desktop access. Do not run startxfce4 inside SSH expecting a desktop window.
1. Check Ubuntu and refresh packages
Confirm the distribution and check SSH is running. Keep this SSH connection open while configuring the desktop.
cat /etc/os-release
systemctl status ssh --no-pager
sudo apt update
Keep the existing network setup. Do not switch network managers while relying on this SSH connection.
If packages are missing: enable Universe
Use this optional Ubuntu-only step if apt cannot locate the desktop packages and Universe is not enabled. Do not add Ubuntu repositories to Debian or another distribution.
Only if needed
sudo apt install software-properties-common
sudo add-apt-repository universe
sudo apt update
2. Install the full Xfce desktop and login screen
Xorg is the display server; xfce4 is the desktop; xfce4-goodies adds plugins and utilities. LightDM supplies the graphical login screen, lightdm-gtk-greeter its login interface, and dbus-x11 supports the X11 session.
sudo apt install xorg xfce4 xfce4-goodies lightdm lightdm-gtk-greeter dbus-x11
Select lightdm if asked which display manager to use. Keep APT's normal recommended packages enabled. This installs an actual Xfce desktop, not just the Xorg server. Add the desktop applications below as needed.
LightDM GTK greeter
3. Select and check LightDM
Choose lightdm when prompted. There may be no selection prompt on a fresh system where it is the only installed display manager.
sudo dpkg-reconfigure lightdm
cat /etc/X11/default-display-manager
Expected result: a path ending in /lightdm. Selecting it changes the default login manager if another one was already installed.
4. Enable graphical boot and start the desktop
Set graphical mode as the boot default and start LightDM now. View its login screen on the attached monitor or VM console, choose the Xfce session if a session selector is shown, and sign in as your normal user.
sudo systemctl set-default graphical.target
sudo systemctl start lightdm
systemctl get-default
systemctl status lightdm --no-pager
Expected: graphical.target and an active LightDM service. These steps target a fresh console-only setup. The SSH terminal itself will not become a desktop.
systemctl commands
5. Verify installation and reboot when ready
Check the Xfce version and display manager. Once the GUI works, save work and reboot at a suitable time to confirm automatic graphical startup. Reconnect over SSH after the machine returns.
xfce4-session --version
systemctl status display-manager --no-pager
# Optional, after saving work and confirming console access:
sudo reboot
Reboot disconnects SSH. Run echo "$XDG_CURRENT_DESKTOP" inside an Xfce terminal to inspect that desktop session; its value in SSH does not verify the local GUI.
If the graphical login does not appear
Use SSH to inspect the selected login manager and current-boot logs. Check that the host has a usable display/GPU or a VM display device, and look for an Xfce session file.
systemctl get-default
cat /etc/X11/default-display-manager
systemctl status lightdm --no-pager
sudo journalctl -u lightdm -b -n 100 --no-pager
ls /usr/share/xsessions/
Investigate the actual LightDM/Xorg error. Do not globally enable root Xorg, change tty permissions or disable SSH to work around an unknown failure.
Docklike Taskbar
Install the panel plugin, then right-click the panel → Panel Preferences → Items → Add → Docklike Taskbar. Pin preferred apps and enable grouping in its settings. Remove Window Buttons only after the replacement works.
Current setup
sudo apt install xfce4-docklike-plugin
Your notes confirm Docklike Taskbar was installed and configured.
Screen locking and sleep
Open Settings → Screensaver and Settings → Power Manager. Configure idle locking, lock-on-sleep and plugged-in sleep separately. Screen blanking, locking and suspend are different controls.
Current setup
Your notes say automatic locking was disabled. Choose the behavior appropriate for this machine.
Desktop applications and removable-drive support
Complete the desktop with the Xfce terminal, Mousepad text editor, Thunar file manager, removable-drive support, power management and screensaver. APT leaves already-installed packages in place.
Optional
sudo apt install xfce4-terminal mousepad thunar thunar-volman gvfs-backends udisks2 xfce4-power-manager xfce4-screensaver
These belong to the full desktop path. They are not required for the Xorg-only kiosk path.
Start your application inside Xfce
For an app running within the full desktop, open Settings → Session and Startup → Application Autostart → Add. Set the command to your tested app launcher, using an absolute path.
This keeps Xfce's panel, window manager and desktop services. To run only an app on Xorg, follow Xorg-only kiosk instead.
Useful desktop tools
Mousepad and Thunar are already part of a typical Xubuntu installation. Add only missing applications.
Optional
sudo apt install micro remmina remmina-plugin-rdp vlc galculator file-roller unzip zip 7zip
Optional fonts and appearance
Select installed themes through Settings → Appearance and Settings → Window Manager.
Optional
sudo apt install fonts-noto fonts-noto-color-emoji fonts-liberation papirus-icon-theme arc-theme
Xubuntu running inside VMware
Install these inside a Linux guest, not on the Linux host for a Windows guest.
Optional
sudo apt install open-vm-tools open-vm-tools-desktop
Xorg-only kiosk
Path 2: install only the Xorg display stack and run your kiosk app directly. No Xfce desktop, panel or LightDM login manager is needed.
Path 2: Xorg and your application only
Start from a console-only Ubuntu system. Install packages over SSH, then test the graphical session from the attached keyboard/monitor or VM console. Follow this path instead of installing the full Xfce desktop.
The kiosk app must provide its own fullscreen behavior and exit path. No window manager or desktop is installed here, so apps requiring those services may need additional setup. SSH remains useful for administration; it does not display the kiosk screen.
1. Install Xorg without a desktop
Install the display server, startx/xinit, display utilities, input driver, fonts and D-Bus session support. Then create a dedicated normal kiosk user if that account does not already exist.
sudo apt update
sudo apt install --no-install-recommends xserver-xorg xinit x11-xserver-utils xserver-xorg-input-libinput fonts-dejavu-core dbus-x11
sudo adduser kiosk
Do not install xfce4, xubuntu-desktop or lightdm for this path. Install your app's own runtime dependencies separately. Use a local console session for startx; do not globally enable root Xorg or add users to tty to bypass an unknown permission error.
2. Prepare and test your app launcher
Install your application for the kiosk user. Use a launcher that sets its working directory and starts the app in fullscreen. The example path below is ~/kiosk/start-app.sh; replace it with your actual executable launcher throughout this guide.
chmod +x "$HOME/kiosk/start-app.sh"
Run this as the kiosk user, not your SSH administrator account. The launcher must already exist. For an installed application, use its real launcher rather than inventing a Python path.
3. Start the app directly in .xinitrc
Log in as the kiosk user. Save the following file as ~/.xinitrc. It disables X screen blanking and runs the application with a session bus. No Xfce session is started.
#!/bin/sh
xset s off
xset -dpms
xset s noblank
exec dbus-run-session -- "$HOME/kiosk/start-app.sh"
The launcher should keep the main app in the foreground, normally using exec. When the app exits, the X session ends. An xset DPMS warning can mean the display driver does not support that feature.
4. Test from the local console
Sign in as the kiosk user at the machine's physical console or VM console, then run startx. Confirm the app appears, input works and you can exit cleanly before enabling automatic startup.
startx
Do not run this command through an ordinary SSH login or sudo. If X fails, inspect ~/.local/share/xorg/Xorg.0.log or /var/log/Xorg.0.log and the current boot journal before changing permissions.
5. Start X after the kiosk user logs into tty1
For a Bash login shell, add this to the kiosk user's ~/.profile after existing setup. If ~/.bash_profile already exists, add it there instead, since Bash reads that file in preference to ~/.profile. Do not replace the rest of the file.
Optional
if [ -z "$DISPLAY" ] && [ "$(tty)" = "/dev/tty1" ]; then
exec startx
fi
6. Optional: automatically log in on tty1
Use sudo systemctl edit getty@tty1.service, then insert the configuration below. This logs in kiosk without a password on tty1.
Optional
[Service]
ExecStart=
ExecStart=-/sbin/agetty --autologin kiosk --noclear %I $TERM
7. Use console boot, then test a restart
After manual startx succeeds, select console boot. The tty1 login and profile start the kiosk app; graphical.target and LightDM are not used. Save work before restarting, and keep SSH access for recovery.
Optional
sudo systemctl daemon-reload
sudo systemctl set-default multi-user.target
sudo reboot
Disable automatic kiosk startup
Remove the tty1 startx block from the kiosk user's profile. If you added the getty autologin override, remove only those added lines using systemctl edit. Keep console boot to return to a normal text login.
sudo systemctl edit getty@tty1.service
sudo systemctl daemon-reload
sudo systemctl set-default multi-user.target
If you later want a desktop, install it using Full Xfce desktop and then select graphical boot. Merely changing the boot target cannot supply a desktop that was never installed.
1. ext4 format & auto-mount
Set up a Linux data partition from start to finish, or automatically mount an existing ext4 partition without formatting it.
Choose your task
New or disposable partition: follow steps 1–7. Existing ext4 partition with files to keep: skip step 3 (formatting) and continue at step 4. Switching from NTFS: copy and verify your files onto another drive first, then format and restore; there is no in-place conversion in this guide.
Formatting erases the selected partition. These steps are for an existing secondary data partition, not repartitioning or reinstalling the operating system.
1. Identify the correct partition
Match size, model and existing filesystem. The partition is the child entry, such as /dev/sdb1; /dev/sdb is the whole disk. If there is no partition yet, create one first using Disks or GParted after backing up the disk.
lsblk -o NAME,SIZE,MODEL,TRAN,FSTYPE,LABEL,UUID,MOUNTPOINTS
df -h
2. Set your partition, mount folder and label
Run the steps for your chosen task in the same terminal so the variables remain set. Replace /dev/REPLACE_WITH_PARTITION with the partition identified by lsblk (for example /dev/sdb1 or /dev/nvme1n1p1). Never select the system/root partition. Storage and /mnt/storage are generic examples you may change.
Partition="/dev/REPLACE_WITH_PARTITION"
Mount_Dir="/mnt/storage"
Label="Storage"
3. Format as ext4 — only if erasing it
Close files and applications using the partition. If findmnt shows it is mounted, run the unmount command and stop if it fails. If already unmounted, skip only the unmount line. Then run mkfs only after verifying the backup.
Erases the selected partition
findmnt --source "${Partition:?Set Partition in step 2}"
sudo umount "$Partition"
# Run separately only after confirming the partition is unmounted:
sudo mkfs.ext4 -L "${Label:?Set Label}" -m 1 "$Partition"
Do not run this step for an existing filesystem you want to keep. -L sets the label; -m 1 reserves 1% for root. No force flag is needed.
ext4 formatting options
4. Create the mount folder and read the UUID
Use the UUID shown after formatting, or the current UUID for an existing ext4 partition. Confirm TYPE is ext4.
sudo mkdir -p "${Mount_Dir:?Set Mount_Dir}"
sudo blkid "${Partition:?Set Partition}"
5a. Back up and open fstab
Use the editor to add the line in step 5b. If this partition already has an entry, update that line; do not create duplicate mount entries.
sudo cp -a /etc/fstab "/etc/fstab.backup-$(date +%Y%m%d-%H%M%S)"
sudoedit /etc/fstab
5b. Add the automatic mount entry
This is a line for /etc/fstab, not a terminal command. Replace REPLACE_WITH_UUID with the actual UUID from step 4. Change /mnt/storage if you chose another folder.
UUID=REPLACE_WITH_UUID /mnt/storage ext4 defaults,nofail,x-gvfs-show 0 2
UUID identifies the filesystem even if its device path changes. nofail allows boot when the disk is missing; x-gvfs-show requests a file-manager entry. The last 2 enables normal non-root filesystem checking. fstab uses literal values, not shell variables.
Filesystem configuration reference
6. Validate and mount
Fix any reported fstab errors before continuing. If the partition is mounted elsewhere, unmount it normally first. Mounting this folder uses the fstab entry. Reboot only after the local mount test succeeds.
sudo systemctl daemon-reload
sudo findmnt --verify --verbose
sudo mount "${Mount_Dir:?Set Mount_Dir}"
findmnt -o SOURCE,FSTYPE,OPTIONS,TARGET "$Mount_Dir"
Expected result: your selected partition, ext4, and rw in the options. If mount reports an error, do not continue to ownership or copying.
7. Give your user access to a new data filesystem
After verifying this is the intended mounted filesystem, give your current desktop user ownership of its top-level directory. Run from your normal user shell, not a root shell. Existing files are not recursively changed.
mountpoint -q "${Mount_Dir:?Set Mount_Dir}" && \
sudo chown "$(id -u):$(id -g)" "$Mount_Dir"
ls -ld "$Mount_Dir"
For shared or existing filesystems, choose ownership according to who should access them; do not overwrite intentional ownership.
Check the mount after reboot
Confirm automatic mounting and available space. Reset Mount_Dir if opening a new terminal.
Mount_Dir="/mnt/storage"
findmnt "$Mount_Dir"
df -h "$Mount_Dir"
If unmount says the partition is busy
Close file-manager windows, applications and terminals inside the mount. This command lists processes using it; close them normally and retry unmounting.
sudo apt install psmisc
sudo fuser -vm "${Mount_Dir:?Set Mount_Dir}"
Do not force or lazy-unmount a filesystem immediately before formatting it.
2. Change swap size
Choose a swap-file size, activate the replacement, make it persistent and safely retire the old file. Includes increasing and decreasing swap.
Choose: add swap or replace existing swap
To add swap, follow steps 1–5 and leave other swap areas alone. To replace a swap file with a larger or smaller one, also follow steps 6–7. These instructions use a new file so the active one is never overwritten.
This procedure is for a normal ext4 filesystem. Btrfs and other copy-on-write filesystems need their own swap-file setup. Swap partitions and zram are different; do not delete or reformat them with these commands. Hibernation/resume configuration is outside this guide.
1. Check memory, swap and free space
Record the exact filename of any old swap you intend to replace. Keep enough disk space for the new file while the old one still exists.
swapon --show
free -h
df -h /
findmnt -no FSTYPE /
2. Choose the size and a new filename
Set Size_GiB to the desired total size for this file: 8, 16 or 32 are examples, not recommendations for every machine. Keep this terminal open for the next steps. /swap-new.img must not already exist.
Size_GiB=32
New_Swap="/swap-new.img"
A smaller replacement needs enough available RAM and other swap to deactivate the old one. More swap does not substitute for RAM performance.
3. Allocate the new file
This block refuses an existing path, creates a root-only file, then fills it with zeros. Wait for it to finish successfully; do not continue after an error.
if sudo test -e "${New_Swap:?Set New_Swap}" || sudo test -L "$New_Swap"; then
printf "File already exists; choose a different New_Swap path.\n"
else
sudo install -m 600 /dev/null "$New_Swap" && \
sudo dd if=/dev/zero of="$New_Swap" bs=1M count="$((${Size_GiB:?Set Size_GiB} * 1024))" status=progress
fi
Use a positive whole number for Size_GiB. This allocates real space, unlike a sparse file. If allocation fails, the file is incomplete: do not initialize or activate it.
Swap-file requirements
4. Initialize and activate
Run only after allocation completed successfully. Confirm the new file and intended size appear in swapon output.
sudo chmod 600 "${New_Swap:?Set New_Swap}" && \
sudo mkswap "$New_Swap" && \
sudo swapon "$New_Swap"
swapon --show
5a. Back up and edit fstab
Add the new swap line shown in step 5b. When replacing a file, remove or comment out only the old file’s line. Keep unrelated swap partitions or zram settings intact.
sudo cp -a /etc/fstab "/etc/fstab.backup-$(date +%Y%m%d-%H%M%S)"
sudoedit /etc/fstab
5b. Add the persistent swap entry
Add this literal line to /etc/fstab. If you chose a different filename, use that exact path instead.
/swap-new.img none swap sw 0 0
6. Replacement only: deactivate the old file
Replace the placeholder with the old swap filename from step 1, not the new one. Close memory-heavy applications first. If swapoff fails, keep the old file and resolve memory pressure before trying again.
Old_Swap="/REPLACE_WITH_OLD_SWAP_FILE"
sudo swapoff "$Old_Swap"
swapon --show
Do not use swapoff -a: deactivate only the file being replaced. An old swap partition is not a file to delete.
7. Validate and check after reboot
Resolve fstab errors before restarting. After your next planned reboot, repeat swapon --show and free -h. The new file should be active; the replaced file should not be.
sudo systemctl daemon-reload
sudo findmnt --verify --verbose
swapon --show
free -h
Optional: remove the inactive old swap file
After the replacement works after reboot, confirm the old path is a regular file and is absent from both active swap and fstab. Then remove only that old file.
Old_Swap="/REPLACE_WITH_OLD_SWAP_FILE"
swapon --show
grep -nF -- "$Old_Swap" /etc/fstab
# Only after checking it is inactive and no longer configured:
sudo rm -i -- "$Old_Swap"
The last command asks before deleting. Keep the file if you are unsure; it only consumes disk space while inactive.
3. NTFS format, repair & copy
Choose the job you need: format a Windows-compatible data partition, mount an existing one, recover files, copy and verify data, or safely eject a USB disk.
Choose your task
Use A to erase and format a partition, B to mount an existing NTFS filesystem, C to investigate mounting errors, D to copy/verify files, or E to eject a USB disk. Start with the device check below for every path. Do not format a disk just because it will not mount.
Start: identify the partition and set variables
Run the steps for your chosen task in the same terminal so the variables remain set. Replace /dev/REPLACE_WITH_PARTITION with the partition identified by lsblk (for example /dev/sdb1 or /dev/nvme1n1p1). Never select the system/root partition. Storage and /mnt/storage are generic examples you may change.
lsblk -o NAME,SIZE,MODEL,TRAN,FSTYPE,LABEL,UUID,MOUNTPOINTS
Partition="/dev/REPLACE_WITH_PARTITION"
Mount_Dir="/mnt/storage"
Label="Storage"
Use the partition path, not the whole disk. Install NTFS tools with sudo apt install ntfs-3g if missing. The same tools provide mkfs.ntfs and ntfsfix.
A. Format a partition as NTFS
Back up everything needed first. Close applications using the partition. If findmnt shows it mounted, unmount it and stop if that fails. If already unmounted, skip the unmount line. Run the format command only after confirming the target is correct.
Erases the selected partition
sudo apt install ntfs-3g
findmnt --source "${Partition:?Set Partition}"
sudo umount "$Partition"
# Run separately after confirming it is unmounted and backed up:
sudo mkfs.ntfs -Q -L "${Label:?Set Label}" "$Partition"
-Q performs a quick format; -L sets a label of your choice. This is neither a repair nor a secure erase. Continue with B to mount it.
NTFS formatting options
B1. Mount through the desktop
For an existing healthy NTFS volume, skip formatting and mount it as your normal desktop user. Use the TARGET path reported by findmnt in any copy commands.
udisksctl mount -b "${Partition:?Set Partition}"
findmnt -o SOURCE,FSTYPE,OPTIONS,TARGET --source "$Partition"
The mount might be under /media/your-user/your-label or /run/media/your-user/your-label. Do not assume the path from a drive name.
B2. Optional: mount NTFS automatically
For a fixed mount path, get the UUID and your numeric user/group IDs, create the folder, then back up and edit fstab. Unmount any desktop mount before testing the fstab entry.
sudo apt install ntfs-3g
sudo blkid "${Partition:?Set Partition}"
id -u
id -g
sudo mkdir -p "${Mount_Dir:?Set Mount_Dir}"
sudo cp -a /etc/fstab "/etc/fstab.backup-$(date +%Y%m%d-%H%M%S)"
sudoedit /etc/fstab
Use the template in B3. If you only want to click the drive in the file manager, B1 is enough.
B3. NTFS fstab template
Replace the UUID and numeric UID/GID placeholders with B2’s results. Keep the mount folder consistent. This template uses the ntfs-3g driver installed above.
UUID=REPLACE_WITH_UUID /mnt/storage ntfs-3g uid=REPLACE_WITH_UID,gid=REPLACE_WITH_GID,umask=022,nofail,x-gvfs-show 0 0
Do not paste shell substitutions into fstab. umask=022 gives the owner write access and others read access; use 077 instead for access limited to the owner.
B4. Validate and test automatic mounting
Fix validation errors first. If mounted through the desktop already, unmount it normally before mounting at the configured path.
sudo systemctl daemon-reload
sudo findmnt --verify --verbose
sudo mount "${Mount_Dir:?Set Mount_Dir}"
findmnt -o SOURCE,FSTYPE,OPTIONS,TARGET "$Mount_Dir"
C1. Diagnose mounting errors
Check the filesystem type and kernel messages first. The following repair steps apply only to NTFS, never ext4. If a drive repeatedly disconnects or logs I/O errors, check cable, enclosure and power and prioritize a backup.
lsblk -o NAME,SIZE,MODEL,TRAN,FSTYPE,LABEL,UUID,MOUNTPOINTS
sudo dmesg | grep -Ei 'ntfs|corrupt|usb|reset|disconnect|I/O error' | tail -n 40
C2. Try read-only access to recover files
If not already mounted, try a read-only mount before changing filesystem metadata. If mounted elsewhere, unmount it normally first. Copy accessible important files to another disk using D.
sudo apt install ntfs-3g
sudo mkdir -p "${Mount_Dir:?Set Mount_Dir}"
sudo mount -t ntfs-3g -o ro "${Partition:?Set Partition}" "$Mount_Dir"
findmnt -o SOURCE,FSTYPE,OPTIONS,TARGET "$Mount_Dir"
Look for ro in the mount options. Do not continue with repairs while this read-only mount remains mounted. If the drive is failing physically, repeated repair attempts can worsen recovery prospects.
C3. Inspect and attempt basic NTFS repair
Unmount the partition first, including any read-only recovery mount. Use -n to inspect without writes. Review its output before deciding to run ntfsfix without -n. Stop if unmount fails.
sudo umount "${Partition:?Set Partition}"
sudo ntfsfix -n "$Partition"
# After reviewing the inspection, with the partition still unmounted:
sudo ntfsfix "$Partition"
If already unmounted, skip the unmount command. ntfsfix handles limited NTFS inconsistencies; it is not the equivalent of Windows chkdsk.
C4. Clear the dirty flag when repair permits it
After successful basic repair, with the partition still unmounted, this option clears the dirty flag only if ntfsfix can process the volume successfully. Then retry a normal mount using B1.
sudo ntfsfix -d "${Partition:?Set Partition}"
Do not use this to bypass Windows hibernation or unresolved errors. Resume Windows and shut it down fully for a hibernated volume.
ntfsfix options and limitations
C5. Persistent errors: use Windows chkdsk
In a Windows Administrator Command Prompt, replace X: with the verified drive letter. Back up readable files first. Finish by fully shutting down Windows before returning to Linux.
chkdsk X: /f
This is a Windows command, not a Linux terminal command.
D1. Choose source and destination folders
Set actual existing paths. The destination must be on a different disk for a backup before formatting. Check mounts and free space first. For a virtual machine, fully power it off and copy the entire VM folder, including separately referenced disks.
Source_Dir="/REPLACE_WITH_SOURCE_FOLDER"
Destination_Dir="/REPLACE_WITH_DESTINATION_FOLDER"
findmnt -T "$Source_Dir"
findmnt -T "$Destination_Dir"
df -h "$Source_Dir" "$Destination_Dir"
Create your chosen destination folder on the confirmed mounted disk before running these checks. Do not use a folder on the partition you intend to format as its backup. Keep source files unchanged while copying and verifying.
D2. Copy the folder contents
Install rsync and run the copy after checking D1. Trailing slashes copy the contents, rather than adding another source directory. Files with the same names in the destination may be replaced.
sudo apt install rsync
test -d "${Source_Dir:?Set Source_Dir}" && test -d "${Destination_Dir:?Set Destination_Dir}" && \
rsync -a --no-owner --no-group --no-perms --sparse --info=progress2 \
"$Source_Dir/" "$Destination_Dir/"
These options suit ordinary files and VM copies across NTFS: they do not preserve Unix owners, groups or permissions. They are not a full Linux system backup. No personal-folder exclusions or --delete are included.
rsync reference
D3. Verify the copied files
This checksum dry run reads and compares files without changing the destination. Success means both exit status 0 and no itemized changes. Run the status line immediately afterward.
test -d "${Source_Dir:?Set Source_Dir}" && test -d "${Destination_Dir:?Set Destination_Dir}" && \
rsync -a --no-owner --no-group --no-perms --checksum --dry-run --itemize-changes \
"$Source_Dir/" "$Destination_Dir/"
printf "Exit status: %s\n" "$?"
Status 0 alone does not mean the folders match. Extra destination-only files are not checked by this comparison. To restore after formatting, select the backup as Source_Dir and the mounted new filesystem folder as Destination_Dir, then repeat D2–D3. Keep the backup until a second safe copy exists.
E. Safely eject a USB disk
Close files and terminals on the disk. Set Disk to its verified parent disk from lsblk, such as /dev/sdb, and Partition to the correct child. Unmount every partition on that disk before powering it off.
Disk="/dev/REPLACE_WITH_USB_DISK"
udisksctl unmount -b "${Partition:?Set Partition}" && \
udisksctl power-off -b "$Disk"
Only use power-off for the intended external USB disk, never an internal/system drive. If busy, close the applications using it; do not force removal.
Tailscale & networking
Connection checks first; installation and the previous repository workaround are kept separate.
Check your connection
Read the installed version, daemon state, peers and this machine’s Tailscale IPv4 address.
Current setup
tailscale version
systemctl is-active tailscaled
tailscale status
tailscale ip -4
Your setup notes recorded Tailscale 1.104.1 installed. Use the command above for the actual current version.
Start and authenticate
Start the service, then follow the authentication URL in the terminal. Existing customized configurations may require preserving their flags.
sudo systemctl enable --now tailscaled
sudo tailscale up
Install on a supported Ubuntu release
Check your codename and Tailscale’s package page first. Download and inspect the official installer, then run it. This replaces piping an unread script directly into a shell.
cat /etc/os-release
curl -fsSL https://tailscale.com/install.sh -o /tmp/tailscale-install.sh
less /tmp/tailscale-install.sh
sh /tmp/tailscale-install.sh
Supported package repositories
Recorded 26.10 repository workaround
Your notes say the installer did not recognize Xubuntu 26.10, so Ubuntu 26.04’s resolute repository was used. This records the existing setup; it is not a recommendation to mix release repositories on a new install.
Historical
sudo install -d -m 0755 /usr/share/keyrings
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/resolute.noarmor.gpg | sudo tee /usr/share/keyrings/tailscale-archive-keyring.gpg >/dev/null
curl -fsSL https://pkgs.tailscale.com/stable/ubuntu/resolute.tailscale-keyring.list | sudo tee /etc/apt/sources.list.d/tailscale.list
sudo apt update
sudo apt install tailscale
Recheck the official package page for your exact release before reusing this workaround or upgrading. Do not add a duplicate repository.
Tailscale package support
Inspect network configuration
Read-only interface, address and routing checks.
ip -brief address
ip route
nmcli device status
Optional .local names
Install only if local hostname discovery is useful on your network. Replace PC-Name with the target hostname.
Optional
sudo apt install avahi-daemon libnss-mdns
sudo systemctl enable --now avahi-daemon
ping PC-Name.local
VMware Workstation
Reference from the removed Ubuntu installation. VMware installation on the current Xubuntu machine is not confirmed.
Install Workstation on the host
Install Build tools from Dependencies first. Download a compatible Workstation Pro Linux installer from Broadcom. Replace the example filename with the exact downloaded file.
Previous installation
sudo apt install "linux-headers-$(uname -r)" mokutil
cd ~/Downloads
ls -lh VMware-Workstation-*.bundle
sudo sh ./VMware-Workstation-FULL-VERSION.x86_64.bundle
Check release notes for your Ubuntu and kernel versions. Avoid executing a wildcard that could expand to multiple installers.
Broadcom support
Build modules after installation
Close running VMs first. Rebuild when required after a kernel or Workstation update.
Previous installation
sudo vmware-modconfig --console --install-all
vmware
Diagnose module loading
Check Secure Boot, current kernel, module locations and the vmmon device.
Previous installation
mokutil --sb-state
uname -r
modinfo vmmon
modinfo vmnet
ls -l /dev/vmmon
Create and enroll a signing key
Only if Secure Boot is enabled and unsigned VMware modules are blocked. The key from the removed Ubuntu installation must not be assumed to exist here. Inspect existing keys first; preserve private keys.
Previous installation
sudo ls -l /var/lib/shim-signed/mok/
sudo update-secureboot-policy --new-key
sudo mokutil --import /var/lib/shim-signed/mok/MOK.der
Set an enrollment password. After signing the modules, reboot and complete MOK enrollment in the firmware screen.
Broadcom module-signing instructions
Sign vmmon and vmnet
Requires successfully built modules, matching kernel headers, and the key files from the previous step. Re-sign modules after rebuilding them.
Previous installation
sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 /var/lib/shim-signed/mok/MOK.priv /var/lib/shim-signed/mok/MOK.der "$(modinfo -n vmmon)"
sudo /usr/src/linux-headers-$(uname -r)/scripts/sign-file sha256 /var/lib/shim-signed/mok/MOK.priv /var/lib/shim-signed/mok/MOK.der "$(modinfo -n vmnet)"
modinfo -F signer vmmon
modinfo -F signer vmnet
Verify after MOK enrollment
After rebooting and completing enrollment, load the signed modules. A signer name alone does not prove the key is enrolled.
Previous installation
sudo mokutil --test-key /var/lib/shim-signed/mok/MOK.der
sudo modprobe vmmon
sudo modprobe vmnet
ls -l /dev/vmmon
Windows guest integration
On the previous host, windows.iso was under /usr/lib/vmware/isoimages/. Attach it through VM → Settings → CD/DVD → Use ISO image file, then run the installer inside Windows. Newer installations may require a separate VMware Tools download.
Previous installation
ls -lh /usr/lib/vmware/isoimages/
mkdir -p ~/VM-Share
Configure Shared Folders, clipboard and drag-and-drop in VM settings. Test 3D acceleration both ways if console rendering freezes; no universal setting is assumed.
Previous freezing investigation
These read-only checks were suggested but not confirmed as run. The investigation stopped when Ubuntu was replaced with Xubuntu.
Historical
dpkg-query -W libx11-6
ls -l /usr/lib/vmware/lib/libX11.so.6/
KVM & virtual machines
An alternative to VMware. Commands below consistently use the system libvirt connection.
Install KVM tools
For an x86 Ubuntu host with hardware virtualization enabled in firmware.
sudo apt install qemu-kvm qemu-utils libvirt-daemon-system libvirt-clients virt-manager virtinst
sudo usermod -aG libvirt,kvm "$USER"
Log out and back in for new group membership to apply.
Open and list virtual machines
Use the system connection in both virt-manager and virsh so they show the same machines.
virt-manager --connect qemu:///system
virsh --connect qemu:///system list --all
Start a virtual machine
Replace myvm with a name from the VM list.
virsh --connect qemu:///system start myvm
Graceful shutdown
Requests a normal guest shutdown; it may take time or require guest integration.
virsh --connect qemu:///system shutdown myvm
Force power off an unresponsive VM
Equivalent to cutting power. Unsaved guest data may be lost. This does not delete the VM definition or disk.
virsh --connect qemu:///system destroy myvm
Corrected the old guide’s “Delete Machine” label.
virsh lifecycle commands
Create a VM interactively
Use virt-manager → Create a new virtual machine. Choose the installation ISO, guest OS, memory, CPUs, disk and network explicitly. This avoids a copied CLI example with obsolete flags and unknown paths.
Optional Cockpit web management
Provides a browser interface for system and VM administration. Restrict access to trusted networks.
Optional
sudo apt install cockpit cockpit-machines
sudo systemctl enable --now cockpit.socket
Troubleshooting
Inspect first, then make a targeted change. Keep the exact error and command output with your notes.
Read failed services and boot errors
These commands inspect state without restarting services.
systemctl --failed
journalctl -b -p err --no-pager
journalctl -u tailscaled -n 80 --no-pager
OpenCV / Qt font or plugin errors
Check which OpenCV distribution is installed in the active environment. If Singularity supplies the UI and never calls cv2.imshow, use only opencv-python-headless. Do not copy fonts into a hardcoded Python version’s site-packages directory.
python -m pip list | grep -i opencv
python -c "import cv2; print(cv2.__file__)"
Optional temporary dummy interface
For isolated development only. Confirm 192.168.7.0/24 is not used by your LAN, VPN or a real device. Do not replace a global multicast route just to test an interface.
Optional
sudo ip link add dummy0 type dummy
sudo ip addr add 192.168.7.1/24 dev dummy0
sudo ip addr add 192.168.7.11/24 dev dummy0
sudo ip addr add 192.168.7.21/24 dev dummy0
sudo ip link set dummy0 up
sudo ip link set dummy0 multicast on
Temporary until reboot. If dummy0 already exists, inspect it before changing it.
Remove the test dummy interface
Only remove dummy0 if it is the interface you created for this test.
sudo ip link delete dummy0
Singularity .Coordination folder
Task locks prevent conflicting program and asset operations. Recipe_Readers protects assets still used by loaded tasks. Hashed task-lock directories correspond to application base paths; older directories can remain after moving an installation.
You may clear Data/.Coordination only after Singularity and every background task, trainer and service process have stopped. It is recreated automatically. Do not clear it while processes are active.
Singularity Vision
Set up the Linux machine, let the installer prepare its private Python environment, then launch the Native application. Start with the single prerequisite command in Dependencies.
1. Check the machine and application package
Use the complete Linux package matching your architecture: x86_64 (AMD64) or aarch64 (ARM64). Extract it to a short, user-writable folder on a filesystem that allows execution, such as ~/Singularity. Keep install.sh and Install.ini together. Leave the supplied Python version settings matched to the compiled application binaries.
cat /etc/os-release
uname -m
getconf GNU_LIBC_VERSION
df -h "$HOME"
free -h
Use a glibc-based distribution and a working Xorg desktop, or Wayland with XWayland. Plain SSH is not a graphical session. The installer checks the selected profile’s compatibility before provisioning Python. Install into a Linux filesystem such as ext4 for normal Linux ownership and permissions.
Full Xfce desktop
Xorg-only kiosk
2. Install the system prerequisites
Open Dependencies and use the complete Singularity command at the end. It includes the system requirements for 2D, 3D and database support. The original general-purpose dependency groups remain available above it for other work; you do not need to select them as well for Singularity.
Only the operating-system package step uses sudo. Run the Singularity installer and application as the intended desktop user. Python packages are installed into Singularity/Python by install.sh, not into your system Python.
Open the complete dependency command
3. Choose CPU inference when no NVIDIA GPU is needed
Before installing, edit the existing keys in Install.ini to the values below. Keep the other feature settings you need. This selects CPU ONNX inference without the CUDA trainer; it does not turn the trainer into a CPU trainer.
[Profiles]
IncludeRuntime=true
IncludeNeural=false
[ONNX]
OnnxRuntime=cpu
The supplied INI currently enables CUDA inference and neural training. Change it for a CPU-only machine. Keep Include2D, Include3D, IncludeCamera and IncludeDatabases as required by your programs. ARM64 additionally requires Include3D=false. Do not paste a second copy of these sections or replace the entire INI with this excerpt.
Alternatively: NVIDIA inference or training
For NVIDIA inference, set IncludeRuntime=true and OnnxRuntime=cuda in their existing INI sections. Set IncludeNeural=true only if you need neural training. Install a distribution-supported NVIDIA driver compatible with the installer’s CUDA profile, then check it from a desktop terminal.
nvidia-smi
IncludeNeural=true selects CUDA PyTorch even if ONNX is set to cpu. A successful nvidia-smi confirms driver access, not successful model execution; the installer checks CUDA execution too. Its prebuilt Python packages supply the selected CUDA runtime dependencies, so a separate CUDA Toolkit compiler is not normally needed. ARM64 must use CPU inference with IncludeNeural=false and Include3D=false.
NVIDIA driver guide
4. Run the installer
After installing the system prerequisites and saving Install.ini, open a terminal as your normal desktop user. Substitute your actual installation folder if different.
cd "$HOME/Singularity" &&
bash ./install.sh
The installer checks space, memory and system libraries, installs or reuses private Python, resolves the selected packages, creates the launcher/menu entry and runs final checks. wxPython may build from source and take time. Wait for Done; a launcher appearing before that is not proof that installation succeeded. If application smoke testing is skipped, the complete compiled application still needs checking.
5. Launch and verify
From your graphical desktop, open Singularity Vision in Applications, or run the launcher below. Confirm the window opens, each enabled task comes online, and the tools and hardware used by your inspection work.
cd "$HOME/Singularity" &&
./Singularity
Use the supplied launcher: it selects the private Python and required graphics backends. Do not use sudo as a general fix for loading errors. Keep application data writable by the intended account. Rerun the installer after moving the folder so its launchers/menu entry use the current path.
6. Finish hardware and license setup
For industrial cameras, install the vendor’s Linux driver/GenTL producer and required device permissions; IncludeCamera installs Python dependencies only. For ODBC, install and configure the driver for your database; the prerequisite command supplies the manager/runtime, not a database server. Machine-wide license installation from the UI needs pkexec/polkit plus a running desktop authentication agent.
Desktop/display-server setup and all hardware/vendor drivers are the user’s responsibility. For machine-wide license installation from the UI, separately provide pkexec/polkit and a running desktop authentication agent appropriate to your distribution. These are not included in the prerequisite command; already-licensed normal operation does not require them.
Installation stopped: fix the first error and rerun
Read the first actual error and its surrounding output. Install missing OS packages, correct the selected CPU/GPU profile, or free the requested disk space, then rerun from the same application folder. Completed steps and cached downloads can be reused.
cd "$HOME/Singularity" &&
bash ./install.sh
Keep .install_cache and its tmp build folder on disk. The installer’s starting shared-disk budgets are 8 GiB for base/2D/CPU, 12 GiB with 3D, 20 GiB with 3D and CUDA inference, or 28 GiB with 3D and training; leave more for inspection data. If wxPython compilation is killed for lack of memory, use the one-job command below and review your swap setup.
Swap setup
Storage setup
Retry a wxPython build with one compiler job
Use this after a compiler process is killed because memory is exhausted. It reduces compiler parallelism; it cannot make an undersized system meet the installer’s memory check.
cd "$HOME/Singularity" &&
WXPYTHON_BUILD_ARGS="--jobs=1" bash ./install.sh
The installer requires at least 512 MiB available RAM and 2 GiB available RAM plus swap for its build check. Several GiB of free RAM is more practical. Leave additional resources for running real inspections.
If the window opens but a task fails
Check the app’s Messages and Diagnostics pages, then the task error logs in the installation’s Log folder. Record the task number, selected program, first error, Linux release and Install.ini settings. A successful dependency installation does not prove every program or camera can run.
cd "$HOME/Singularity" &&
./Python/bin/python -B --version &&
./Python/bin/python -B -m pip check
Use this private interpreter for dependency checks. Python package repair does not rebuild App/Lib/Xenonix binaries; deploy matching Linux binaries if the interpreter or application build changed. Keep failed-program data and logs for diagnosis instead of deleting task databases or coordination files while services are running.