Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Debug & Improve Experience

Debian Linux is documented in a comprehensive wiki with descriptions for setting up the system, installing software (packages), and tutorials for trouble shooting. This page provides guidance for problems that may occur in particular when Debian Linux is installed on a Virtual Machine (VM).

Power management (battery life)

Working with Linux on a laptop often drains the battery quickly, especially when working with pure Debian. To increase power efficiency, consider installing lightweight Ubuntu (derivatives), that is Mate editions. Also, the following tool can help improve battery life on Ubuntu (derivatives):

sudo add-apt-repository ppa:linrunner/tlp 
sudo apt update 
sudo apt install tlp tlp-rdw

Alternatively, Fedora or Arch are said to be power efficient. However, Arch can be difficult for Linux novices.

Particular Problems

Root Drive Is Running Out of Disk Space

In general, keep the system clean after updating it through typing in Terminal:

sudo apt clean
sudo apt autoclean
sudo apt autoremove
sudo apt autoremove --purge
sudo apt autoremove

Subversion (SVN) repositories may also contain old and unnecessary chunks, which can be removed (e.g., from a local TELEMAC-MASCARET repository) with (the second argument is the SVN directory):

svn cleanup ~/telemac/v8p1 --non-interactive

If the root partition of the virtual disk is running out of space, Debian prompts a warning message Root drive is running out of disk space [...]. There are many ways described for freeing up space through the deletion of obsolete or unnecessary packages, but this problem may occur even though only absolutely necessary packages are installed on a too small virtual disk.

In the case that the disk space limitation problem occurs on a virtual disk created with VirtualBox, open VirtualBox, highlight the VM subjected to the problem (e.g. Debian Linux). Make sure that the VM is off. In VirtualBox locate the File drop-down menu (top-left), click on it and open the Virtual Media Manager. Highlight the virtual disk where Debian Linux is installed and increase the Size. Click Apply and Close the Virtual Media Manager.

Increasing the virtual disk space alone is not sufficient, because the free disk space needs to be allocated to the root partition. To do so:

Keep System and Software up to Date

Read more on the developer’s website.

Permission Denied Messages

Permission denied messages may occur because of the fail-safe design of Debian, but denied read and write rights may quickly become annoying, in particular if you need to switch between normal and superuser accounts for installing software packages.

This is how to unlock all read and write rights for a directory:

sudo chmod a+rwx /directory

Or for all subdirectories:

sudo chmod a+rwx /directory/*

Or for all files in a directory:

sudo chmod a+rwx /directory/*.*

Or for all sub-directories and files in these directories:

sudo chmod a+rwx /directory/*/*.*

This lifts all restrictions from a directory for all users, all its sub-folders and files contained (and sub-sub-folders and sub-sub-files contained, and so on) -- this can be a very harmful irreversible operation when applied to system directories!:

sudo chmod -R 777 /directory/

Python

tkinter Imports Fail (No Module Named Tkinter)

tkinter is sometimes still only installed for Python2 on Linux, while we want to use it with Python3. To ensure that tkinter for Python3 is installed, install via Terminal:

If the above comments do not work, make sure that the tkinter repository is available to your system: sudo add-apt-repository ppa:deadsnakes/ppa (the repository address may change and depends on your Linux and Python versions).

Wine (Windows Apps)

General wine issues (reinstall)

If wine does not work as desired, remove the current installation via Terminal:

sudo apt remove wine wine32 wine64 libwine libwine:i386 fonts-wine
sudo apt remove --purge wine* 
sudo apt autoremove

Next, remove the wine prefix and any residual configuration files:

rm -rf ~/.wine
rm -rf ~/.local/share/applications/wine

Now, prepare the system for a clean wine installation. Specifically, Wine often needs 32-bit libraries even when creating a 64-bit prefix:

sudo dpkg --add-architecture i386
sudo apt update

If not yet done, add the latest stable Wine version to use the WineHQ repository. First, download and add the repository key:

wget -nc https://dl.winehq.org/wine-builds/winehq.key
sudo apt-key add winehq.key

Then, add the repository. For example, if your Linux Mint version is based on Ubuntu 20.04 (Focal):

sudo apt-add-repository 'deb https://dl.winehq.org/wine-builds/ubuntu/ focal main'
sudo apt update

If your Linux Mint is based on a different Ubuntu release, adjust the repository accordingly.

Now install the stable Wine release:

sudo apt install --install-recommends winehq-stable

Also, consider to install Winetricks, which simplifies installing many runtime libraries and frameworks:

sudo apt install winetricks

64-bit Application Not Working

If a 64-bit msi or other installer / application is not working as desired, try to adapt the WINEPREFIX. First, remove any old prefix if necessary:

rm -rf ~/.wine

Then force Wine to create a 64‑bit prefix:

WINEARCH=win64 winecfg

The wine configuration window will appear. In the “Applications” tab, set the Windows version to Windows 10. Click Apply and OK.

Installing the .NET Framework

Wine can use Winetricks to install various versions of the .NET Framework. Depending on the requirements of a Windows application, you might need a specific version. For example, to install .NET Framework 4.8, use Winetricks (see above) to create a new prefix:

WINEPREFIX=~/.wine winetricks dotnet48

The installation process can take a while and may require several restarts of Wine. Follow the on-screen instructions carefully.

Some users find that certain .NET versions install more reliably in a 32‑bit prefix—even when targeting Windows 10 apps. If you encounter issues, you may try creating a 32‑bit prefix by omitting the WINEARCH=win64 environment variable (or explicitly using WINEARCH=win32). However, note that truly 64‑bit Windows applications require a 64‑bit environment.

QGIS

GPG error - public key not available (APT UPDATE)

Occasionally (literally...), the GPG key of the QGIS repositories become invalid, which results in an error when using:

sudo apt update

[...]

W: An error occurred during the signature verification. The repository is not updated and the previous index files will be used. GPG error: https://ubuntugis.qgis.org/ubuntugis focal InRelease: The following signatures couldn't be verified because the public key is not available: NO_PUBKEY D155B8E6A419C5BE

W: Failed to fetch https://qgis.org/ubuntugis/dists/focal/InRelease  The following signatures couldn't be verified because the public key is not available: NO_PUBKEY D155B8E6A419C5BE

[...]

To troubleshoot this error, note the unavailable key (i.e., D155B8E6A419C5BE in the above example) and then update the unavailable key:

sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys D155B8E6A419C5BE

To test if the key update worked, tap sudo apt update

No module named OpenGL

If QGIS throws the error message ModuleNotFoundError: No module named 'OpenGL', install Mesa as follows on Ubuntu (i.e., Debian Linux) based operating systems (including Mint and Lubuntu).

Bring apt and pip to up-to-date:

sudo apt update
python -m install --upgrade pip

Install the following system packages (if not yet done):

sudo apt install build-essential freeglut3 freeglut3-dev mesa-common-dev binutils-gold libglew-dev libglm-dev python-pyqt5

Install the following Python pip packages:

python -m pip install pyOpenGL
python -m pip install pyOpenGL_accelerate
python -m pip install PyQt5
python -m pip install PyQt5-sip
python -m pip install PyQtWebEngine

A system restart (or just reload the user environment with source ~/.bashsrc) may be necessary for QGIS to work now without the OpenGL error.

LAStools

To get LAStools working in QGIS on Ubuntu (make sure to have Windows Apps on Linux installed):

To troubleshoot a LAStools installation in QGIS read this proposition on rapidlasso.com.

Read more about running LAStools on Ubuntu.

3d Graphics Drivers

GPU intense software requiring strong graphics performance, such as the Unreal Engine, will require newest graphics cards and drivers. The default graphics drivers may not be able to satisfy the needs for such appliances. Latest releases of graphics drivers can be installed through proprietary drivers (e.g., nVidia’s proprietary drivers to replace nouveau drivers).

Here is one option to update nVidia graphic drivers, though be aware that this action can substantially harm your system (it may not reboot) if you are not running an Ubuntu Linux (derivative) with an appropriate nVidia graphics card. So if you are OK with this warning:

sudo apt-cache search 'nvidia-driver-' | grep '^nvidia-driver-[[:digit:]]*'
sudo apt-cache search 'nvidia-dkms-' | grep '^nvidia-dkms-[[:digit:]]*'
[...]
nvidia-dkms-470 - NVIDIA DKMS package
nvidia-dkms-470-server - NVIDIA DKMS package
nvidia-dkms-495 - Transitional package for nvidia-dkms-510
nvidia-dkms-510 - NVIDIA DKMS package
nvidia-dkms-510-server - NVIDIA DKMS package
nvidia-dkms-515 - NVIDIA DKMS package
nvidia-dkms-515-server - NVIDIA DKMS package
sudo apt update
sudo apt full-upgrade
sudo apt install nvidia-driver-515 nvidia-dkms-515
sudo shutdown -r now
nvidia-smi

Mac OS Apps (DMG file handling)

MacOS applications are often distributed as DMG files. Although Linux does not support DMG files natively, they can be converted to a mountable IMG file to then create an ISO image, which is easier to mount and work with on Linux.

Convert the DMG to an IMG

First, install the dmg2img tool:

sudo apt install dmg2img

Convert the DMG file by running:

dmg2img /path/to/file.dmg

This command creates an IMG file with the same basename as the DMG, formatted with Apple’s HFS+ filesystem.

Mount the IMG file

Since the IMG file uses the HFS+ filesystem, load the following kernel module:

sudo modprobe hfsplus

Create a mount point (tpyically, in /media):

sudo mkdir -p /media/user/appname

Mount the IMG file using a loop device:

sudo mount -t hfsplus -o loop /path/to/file.img /media/user/appname

Create an ISO from the mounted IMG

While it is possible to directly work with the mounted IMG, converting it to an ISO improves Linux compatibility. One way to do this is with Brasero, a graphical disc-burning tool for creating ISO images. Thus, first, install Brasero:

sudo apt install brasero

Then follow these steps:

  1. Launch Brasero by opening it from the system menu (typically under Sound & Video) or search for it.

  2. Start a new poject with a click on Data project.

  3. Add files with a click on the plus icon (typically at the top left) and select the folder where the IMG file is mounted (/media/user/appname).

  4. Click Burn, choose an output directory, and optionally change the output image name.

  5. Click Create Image to generate the ISO file.

Mount the ISO image

ISO images are natively supported by Ubuntu. To mount the new ISO:

  1. (Optional) load the HFS+ module:
    If the ISO still uses HFS+ (this is uncommon for standard ISO images), run:

    sudo modprobe hfsplus

  2. Create a mount point for the ISO:

    sudo mkdir -p /media/user/appnameISO

  3. Mount the ISO:
    If the ISO uses HFS+, mount it with:

    sudo mount -t hfsplus -o loop /path/to/file.iso /media/user/appnameISO

    Otherwise, for a standard ISO 9660 filesystem, simply use:

    sudo mount -o loop /path/to/file.iso /media/user/appnameISO

Now, all the contents of the ISO (originally from the DMG/IMG) are accessible in the /media/user/appnameISO directory.

Launching the application from the mounted ISO

The contents of the mounted ISO can be explored to locate the application and launching it. Keep in mind that macOS applications are still not natively executable on Linux. A compatibility layer, such as Darling may be needed.

Locate the application bundle

MacOS apps are typically packaged as .app bundles. Here is how to find them:

Find the executable inside the bundle

Launch the Application

Use Darling (macOS Compatibility Layer)
Run a Cross-Platform App

Since macOS binaries do not run natively on Linux, one option is to use Darling, which provides a translation layer for macOS apps.

  1. Install Darling:
    Follow the instructions on the Darling website to install it on the system.

  2. Launch a Darling shell and run the app:

    darling shell
cd /media/user/appnameISO/MyApp.app/Contents/MacOS
./MyApp

    Note that Darling still is experimental, so not all apps run flawlessly.

Verify and troubleshoot

If the app starts, its GUI should open up or there should be a confirmation message in Terminal.

f the application fails to launch, ensure that:

Troubleshoot
Operating Systems (Linux and VMs)
Troubleshoot
Debugging Virtual Machines