ubuntu2mint

High-risk, best-effort in-place conversion script that keeps Ubuntu as the base OS while adding Linux Mint repositories + Mint desktop/tooling to approximate a Linux Mint system without a full reinstall.

This project is intended for experienced Linux admins who understand APT, repo pinning, display managers, and rollback strategies.

Two scripts, in this order

ubuntu-to-mint-convert-v3.sh	Adds the Mint repositories and installs the Mint desktop stack alongside what is already there. Nothing is removed.
ubuntu-desktop-prune.sh	Afterwards, once you have booted into a working Mint session, removes the Ubuntu GNOME desktop components left behind.

The order matters. Pruning the Ubuntu desktop before you have confirmed a working replacement session leaves you with neither — see Pruning the Ubuntu desktop.

🟥 UNSUPPORTED + PROBABLY DUMB (READ THIS FIRST)
There is no guaranteed safe way to convert Ubuntu to Linux Mint in-place and preserve all corporate software/agents.
EDR/MDM/VPN/compliance tooling may break and require re-enrollment.
A clean install (or a second disk/VM test) is the recommended approach.

The script enforces an interactive “I understand” gate during convert and also requires --i-accept-the-risk.

What this does

• Detects supported Ubuntu bases:
  • Ubuntu 24.04 (noble) → targets Linux Mint 22.x (default 22.3 “zena”)
  • Ubuntu 22.04 (jammy) → targets Linux Mint 21.x (default 21.3 “virginia”)
• Adds the Linux Mint package repository (packages.linuxmint.com)
• Keeps Ubuntu repos for the underlying base system
• Installs Mint meta-packages (desktop + tooling) and configures:
  • LightDM as default display manager
  • slick-greeter as greeter
  • Default desktop session based on --edition
• Applies conservative APT pinning:
  • Ubuntu remains default for overlapping base packages
  • Mint desktop stack is pinned high to avoid mixed-version dependency breakage
• Includes guardrails:
  • APT/dpkg lock detection
  • best-effort dpkg/apt repair (always on; there is no flag to disable it)
  • a pre-install APT simulation that aborts on critical-package removal or too many removals
  • disables third-party sources by default (with allowlist heuristics for common corp repos)
  • backup + rollback support
  • post-conversion validation report written into the backup directory

What this does not do

• It does not replace your OS identity with Mint in a fully supported way.
• It does not guarantee your machine remains compliant in managed enterprise environments.
• It does not guarantee perfect package resolution—APT may still want to remove packages.
• Rollback restores /etc/apt, but may not remove packages installed during conversion (use snapshots/Timeshift for full reversion).
• This script is LightDM-first, which implies X11 sessions; it does not attempt to force Wayland.

Requirements

• Ubuntu 24.04 (noble) or 22.04 (jammy)
• Root access (sudo)
• Working APT and dpkg state (the script can attempt basic remediation)
• Internet access to:
  • Ubuntu mirrors (or your corporate mirror)
  • packages.linuxmint.com
• Recommended:
  • Timeshift snapshot configured
  • Full-disk backup or VM snapshot

Quick start

1) Clone and run doctor checks

git clone https://github.com/Coffey-Labs/ubuntu2mint.git
cd ubuntu2mint
sudo bash ubuntu-to-mint-convert-v3.sh doctor

2) (Optional) Run plan mode (dry-run)

Plan mode simulates the APT changes and writes a log under /var/log/ubuntu-to-mint/.

sudo bash ubuntu-to-mint-convert-v3.sh plan --edition cinnamon

Plan mode uses a temporary APT environment (it does not modify your system’s APT sources). It creates a temporary Mint keyring by downloading and extracting the linuxmint-keyring package.

Plan mode is for decision support. It does not modify /etc/apt or install Mint repos onto your live system.

Plan mode is advisory — it writes the simulation to a log for you to read and does not decide anything. The check that can actually stop a conversion is the gate inside convert (see Safety model), which runs its own simulation against your real APT configuration immediately before installing.

3) Run conversion

sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon

You can skip the secondary interactive confirmation prompts with --yes:

sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk --edition cinnamon --yes

The big red unsupported disclaimer gate is still required during convert even with --yes.

4) Reboot and validate

After conversion:

1. Reboot

2. Login via LightDM and confirm your chosen session loads

3. Validate:

   • VPN connectivity (GlobalProtect, etc.)
   • EDR/MDM agents + compliance posture (CrowdStrike Falcon, etc.)
   • corporate certificates / SSO
   • NetworkManager
   • printers
   • smartcards / YubiKey
   • camera/audio

Usage

sudo bash ubuntu-to-mint-convert-v3.sh doctor
sudo bash ubuntu-to-mint-convert-v3.sh plan [options]
sudo bash ubuntu-to-mint-convert-v3.sh convert --i-accept-the-risk [options]
sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS

Options

Desktop / targets

• --edition cinnamon|mate|xfce Desktop edition meta-package to install (default: cinnamon).

• --target <mint_codename> Override the Mint target codename. Allowed targets depend on your Ubuntu base:

  • Ubuntu noble: zena, zara, xia, wilma
  • Ubuntu jammy: virginia, victoria, vera, vanessa

• --mint-mirror <url> Override Mint mirror base URL (default: http://packages.linuxmint.com)

Safety / APT behavior

• --keep-ppas Do not disable third-party APT sources (not recommended). Default behavior disables PPAs and most third-party repos during conversion and moves them into the backup folder. Some common enterprise repos may be automatically allowlisted.

• --with-recommends Allow installation of recommended packages (default: off for safety).

• --max-removals N Abort if the pre-install simulation would remove more than N packages (default: 40). Critical packages abort regardless of this number.

• --preserve-snap Keep snapd and reinstall it after the Mint stack (this is the default).

• --yes Skip most interactive prompts, and allow overwriting an existing Mint keyring that does not match the expected key. (Does not bypass the convert disclaimer gate or --i-accept-the-risk.)

There is no flag to disable the dpkg/apt repair pre-flight — it always runs. Nor is there flavor-package purging; if a conflicting Ubuntu flavor meta-package causes a login loop, remove it by hand.

Safety model (important)

Guardrails included to reduce “brick your system” outcomes:

• Refuses to run unless on supported Ubuntu bases

• Detects and blocks active APT/dpkg locks

• Attempts to repair basic dpkg/apt broken states before doing anything else

• Disables PPAs by default during conversion (unless --keep-ppas)

• Runs an APT simulation during convert, immediately before the real install, and aborts if:

  • APT wants to remove a critical package — sudo, systemd, libc6, apt, dpkg, network-manager, grub-*, the kernel meta packages, openssh-server. There is no threshold at which removing these is acceptable, so any hit aborts outright.
  • more than --max-removals packages would be removed (default 40)
  • APT cannot resolve the install at all

  Nothing is installed when the gate trips. The full simulation is written to /var/log/ubuntu-to-mint/simulate-YYYYMMDD-HHMMSS.txt.

• Creates a backup directory for rollback

• Post-conversion validation writes a report into the backup directory (always created)

Logs and backups

Logs

• Main log:

  • /var/log/ubuntu-to-mint/ubuntu-to-mint-YYYYMMDD-HHMMSS.log

• Plan logs:

  • /var/log/ubuntu-to-mint/plan-YYYYMMDD-HHMMSS.txt

Backup directory

During convert, a backup directory is created, e.g.:

• /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS/

Contains:

• /etc/apt backup

• package inventories (apt-manual, holds, dpkg list)

• enabled systemd services list

• snap/flatpak lists (if installed)

• disabled third-party sources (if disabled)

• post-convert validation report:

  • post-convert-validation.txt

Rollback

Rollback restores /etc/apt and any disabled sources from the backup:

sudo bash ubuntu-to-mint-convert-v3.sh rollback /root/ubuntu-to-mint-backup-YYYYMMDD-HHMMSS
sudo apt-get update
sudo apt-get -f install

Rollback restores APT configuration but may not remove packages installed during conversion. For full restoration use Timeshift / snapshot / backup.

Troubleshooting

APT update fails after conversion

• Check:

  • /etc/apt/sources.list.d/official-package-repositories.list
  • Mint mirror reachability
  • corporate proxy settings

• If needed:

  • rollback using the backup directory

Desktop won’t start / login loop

• Boot to a TTY (Ctrl+Alt+F3)

• Inspect:

  • journalctl -b -p err
  • user session logs: ~/.xsession-errors

• Reinstall key desktop components:

  • sudo apt-get install --reinstall lightdm slick-greeter cinnamon-session cinnamon-settings-daemon muffin

Key retrieval / keyserver issues

This version avoids keyservers by default. It prefers:

• a locally installed linuxmint-keyring package, or
• downloading the latest linuxmint-keyring_*.deb from the Mint mirror and extracting the keyring

The extracted key is checked against the expected Mint key ID (A6616109451BBBF2) and the run aborts if it is not present, so a substituted keyring fails rather than being trusted.

If your existing keyring does not match, the script stops and tells you to either re-run with --yes to overwrite it, or delete /usr/share/keyrings/linuxmint-repo.gpg by hand and re-run.

Known dpkg overwrite conflict (mintupdate)

Some environments hit a file conflict between mintupdate and software-properties-gtk over an icon file. The script applies a dpkg diversion for that file before installing, and retries the install once with remediation if it still fails.

Login loop after conversion

A leftover Ubuntu flavor meta-package (ubuntucinnamon-desktop and friends) can fight the Mint session and produce a login loop. The script does not purge these — check for them from a TTY and remove them manually if the desktop will not start.

Corporate VPN/EDR breaks

• Reinstall using corporate-provided packages
• Re-enroll if required
• Validate kernel modules, certificate stores, and PAM stack

Pruning the Ubuntu desktop

ubuntu-desktop-prune.sh is the second half of this, and it is destructive: it purges the Ubuntu GNOME desktop rather than adding anything.

Only run it after you have rebooted into a working Mint session. It removes gdm3, gnome-shell and the Ubuntu session packages; if the replacement desktop does not actually work yet, you will be left without either one. plan first, always.

Commands

sudo bash ubuntu-desktop-prune.sh doctor     # environment checks
sudo bash ubuntu-desktop-prune.sh plan       # simulate, change nothing
sudo bash ubuntu-desktop-prune.sh prune --yes
sudo bash ubuntu-desktop-prune.sh rollback /root/ubuntu-desktop-prune-backup-YYYYMMDD-HHMMSS

prune refuses to run without --yes. There is no interactive prompt — the flag is the confirmation.

Options

• --yes — required for prune.
• --max-removals N — abort if the simulation removes more than N packages (default 75). Critical packages abort regardless of this number.
• --with-recommends — allow recommended packages (default: off).
• --skip-dm-fix — do not try to make LightDM the default display manager before pruning. Rarely what you want: the script sets LightDM up first precisely because gdm3 is about to be removed, and skipping that step is how you end up with no display manager at all.

What it removes

A fixed, conservative list — no wildcards — filtered to whatever is actually installed: ubuntu-desktop, ubuntu-desktop-minimal, ubuntu-session, ubuntu-session-minimal, gdm3, gnome-shell and its common/dock packages, the yaru-theme-* set, ubuntu-wallpapers*, gnome-software, snap-store.

Toolkit and library packages that Cinnamon, MATE or Xfce may still depend on are deliberately left alone.

Safety gates

The same shape as the converter's. Before purging, it simulates apt-get purge --autoremove and aborts if:

• a critical package would be removed — sudo, systemd, systemd-sysv, network-manager, openssh-server, or a kernel image. Unconditional.
• more than --max-removals packages would go.
• APT cannot resolve the purge.

It also sets LightDM as the default display manager before removing gdm3, so the machine still has something to boot into.

Backup and rollback

prune writes /root/ubuntu-desktop-prune-backup-YYYYMMDD-HHMMSS/ containing /etc/apt, /etc/lightdm, /etc/X11/default-display-manager, the display-manager.service symlink, and inventories of installed packages, manual selections, holds and enabled services.

rollback restores the APT and display-manager configuration from that directory. It does not reinstall the purged packages — the inventories are there so you can do that yourself, and a snapshot remains the only real undo.

Security & compliance considerations

If this is a corporate-managed device:

• Get explicit approval before modifying base OS repositories
• Confirm your organization’s standard OS images and compliance requirements
• Expect that security tooling may detect drift and require remediation

License

Copyright (C) 2026 Coffey Labs

This project is licensed under the GNU General Public License v3.0. See the LICENSE file or the header in ubuntu-to-mint-convert-v3.sh.

Disclaimer

This project is provided as-is. You assume all risk for system instability, data loss, or compliance impact. Always have a tested restore path before running.