Mint-Doctor

Mint-Doctor

Mint-Doctor

Terminal autorepair tool for Linux Mint 22.3 “Zena” with Cinnamon: it detects, explains and fixes —with your permission— the most common problems in this specific version of the system.

Bash 4+ Linux Mint 22.3 Cinnamon GPLv3 license

🇬🇧 This is the main documentation. For the Spanish version, see 🇪🇸 Leer en español.

Contents

What is Mint-Doctor?

Mint-Doctor is a terminal script that checks Linux Mint 22.3 with Cinnamon for the specific problems that actually affect this version: GPG keys that fail after an update, an NVIDIA driver that stopped loading with the new kernel, a package that breaks GTK4 application rendering, accumulated kernels eating disk space, a Timeshift setup that looks configured but never actually created a snapshot…

It is not a generic cleaner that promises to leave the PC “as good as new”. It is closer to a mechanic’s checklist, built from Mint’s own release notes and from issues that keep coming back in its official forum: it checks one point, explains what it found and why it matters, and only acts when you confirm it.

menu-en-mintdoctor

mint-doctor-menu

The main advantage

Any “maintenance” script can empty a trash bin or run apt autoremove. What makes Mint-Doctor different is that it knows about documented Mint 22.3 issues specifically, including:

On top of that, the design is deliberately conservative:

Installation

git clone https://github.com/filonux/Mint-Doctor.git
cd mint-doctor
chmod +x script/mint-doctor.sh
./script/mint-doctor.sh

There is nothing else you need to install beforehand: everything it uses by default is already present on Linux Mint. If a module detects that a specific tool is missing (smartmontools, TLP, Timeshift, psmisc…), it offers to install it, with your confirmation.

Commands

Command What it does
./script/mint-doctor.sh Opens the interactive menu
./script/mint-doctor.sh --dry-run Simulates actions; nothing is applied
./script/mint-doctor.sh --auto Checks and repairs everything automatically, without the menu
./script/mint-doctor.sh --dry-run --auto Full simulated scan, without the menu
./script/mint-doctor.sh -h, --help Shows the help
./script/mint-doctor.sh -v, --version Shows the version
./script/mint-doctor.sh --lang es Forces the interface to Spanish
./script/mint-doctor.sh --lang en Forces the interface to English

Usage

When started without arguments, Mint-Doctor opens a menu with a quick status panel (disk, RAM, APT, pending updates, network) and ten options:

  1. System information — distribution, kernel, Cinnamon, CPU, disk/RAM and session type. Read-only; it changes nothing.
  2. Packages and APT/dpkg — stale locks, half-installed packages, broken dependencies, held packages, pkexec/sudo permissions.
  3. Software repositories — repositories using an older Mint/Ubuntu codename, missing or invalid GPG keys, unreachable repositories and inherited keyrings.
  4. Disk space and cache — APT cache, accumulated old kernels, thumbnail cache, trash, systemd journal size, unused Flatpak runtimes, missing Flathub remote and an almost-full /boot partition.
  5. Boot, GRUB and clock — GRUB entry for the current kernel, pending reboot, RTC clock problems when dual-booting Windows, NTFS volumes marked as “dirty”, NTP synchronization, failed systemd services and forced shutdowns caused by the new timeout.
  6. Network connectivity — software-blocked radios (rfkill), Internet connectivity and DNS resolution checked separately.
  7. Hardware health — disk S.M.A.R.T. status, battery health and TLP power management, DKMS modules not rebuilt after a new kernel, NVIDIA 470 driver compatibility, sound server, Secure Boot and modules rejected because of missing signatures, VirtualBox Guest Additions.
  8. Cinnamon desktop — recent crashes, desktop shortcuts not marked as trusted, the gstreamer1.0-vaapi package, multimedia codecs, a session running without 3D acceleration and third-party Cinnamon spices compatibility with the installed Cinnamon version.
  9. Backups (Timeshift) — whether a configured destination exists, whether there are real snapshots (not only a completed setup wizard), their age and whether automatic scheduling is enabled.
  10. Run all modules — the same sequence used by --auto, but asking before each step.

Each session is logged under ~/.mint-doctor/ (permissions restricted to your user; the 20 most recent are kept). At the end, a summary shows how many problems were detected, how many were fixed and how many were skipped.

To run it unattended (for example from a systemd --user timer or cron), use --auto: it does not open any menu and returns exit code 1 when a problem remains unresolved (0 otherwise), so a launcher can tell whether anything still needs attention. If a graphical session is available and notify-send is installed, it also sends a desktop notification.

Compatibility

Made and tested for Linux Mint 22.3 “Zena” with Cinnamon (6.6.x). On startup it checks the installed version; if it detects anything outside the 22.x series, it warns you but does not block execution: modules that depend on Cinnamon or Mint-specific paths will simply have nothing to check on a different system.

Turn it into an app with Scriptya

Scriptya, another tool by the same author, turns any script into a standalone app with its own icon, integrated into the Cinnamon menu and/or desktop —and also lets you launch, update or uninstall it from a single menu, without having to write a .desktop file by hand.

mint-doctor.sh already includes the metadata Scriptya knows how to read (MENU, DESCRIPTION, TERMINAL), so you only need to point it at the project folder to get it integrated.

Language

Mint-Doctor includes the full interface in English and Spanish. This main README is in English; the Spanish documentation is available in README.es.md.

By default, the script follows the effective locale (LC_ALL, then LC_MESSAGES, then LANG). If it is Spanish, the interface is Spanish; otherwise it uses English. On GNU/Linux, LANGUAGE is also respected when it explicitly prefers English or Spanish, except under the C/POSIX locale.

You can also choose the language explicitly without editing the script:

./script/mint-doctor.sh --lang es
./script/mint-doctor.sh --lang en

MINT_DOCTOR_LANG=es ./script/mint-doctor.sh
MINT_DOCTOR_LANG=en ./script/mint-doctor.sh

When both are used, --lang takes precedence over the environment variable. If an unsupported language is requested, Mint-Doctor falls back to English.

Tests

The project includes a regression suite for syntax, locale detection, both interface languages, dynamic translations, command-line parsing, the yes/no prompts and a full --dry-run --auto pass. The English and Spanish dry-runs also compare the commands they plan to execute, so changing the language cannot silently change a repair.

Run it from the project root:

./tests/test.sh

The suite uses Bash, Python 3 and the standard Linux tools already available in a typical Mint installation. It never applies a real repair: the end-to-end pass always runs in --dry-run.

Contributing

Issues and pull requests are welcome; there are templates in .github/ for reporting bugs or proposing improvements. The full guide is in CONTRIBUTING.md, and the code of conduct is in CODE_OF_CONDUCT.md. To report a security issue, see SECURITY.md instead of opening a public issue.

License

GPLv3. See LICENSE.txt.

Made by Filonux.

This site is open source. Improve this page.