SMB Mount Wizard

A small PyQt6 desktop app for Debian/KDE Plasma to discover and mount SMB/CIFS network shares, without editing /etc/fstab by hand or digging through Dolphin's network browser every time.

Features

• Discovery - scans the local subnet for SMB hosts (or add one manually by IP/hostname), lists shares, mounts with one click.
• Tailscale-aware - if the tailscale CLI is present, devices on your tailnet are discovered automatically alongside the regular LAN scan, no separate button needed. A device reachable both on the LAN and via Tailscale is shown once, not twice.
• Friendly names, not just IPs - shows a hostname next to each address (from Tailscale's device name, reverse DNS, or a NetBIOS lookup) and uses it for the local mount folder name too (/mnt/nas/storage instead of /mnt/192_168_0_5/storage) - the actual SMB connection always still uses the real IP.
• Guest and authenticated mounts - detects whether a share needs a login before asking, and only prompts for credentials when actually required. Credentials entered for browsing are reused for mounting and vice versa, and are shared across a device's LAN/Tailscale addresses instead of being asked for twice.
• Persistent mounts - optionally writes a proper /etc/fstab entry (x-systemd.automount, credentials in a root-owned file) so a share survives a reboot, instead of requiring a manual re-mount every time.
• Saved credentials - remembers login details via the system keyring (KWallet / Secret Service), only after a mount has actually succeeded.
• Open without mounting - a small folder-icon button next to each share opens it directly in your file manager for a quick look, without committing to a full mount.
• Mounted tab - view active shares grouped by server, a disk usage bar per share, and unmount (with automatic fallback to a lazy unmount for a share whose connection died silently, e.g. after suspend/resume).
• Diagnostics tab - checks for required system tools (nmap, smbclient, cifs-utils, pkexec) plus recommended ones (secret-tool, nmblookup) and installs anything missing.
• Settings - default mount location, SMB protocol version override, and a live-switchable EN/PL interface language.

Screenshots

Discovery	Mounted

Settings	Diagnostics

Installation

1. Clone the repository

git clone https://github.com/TjomekPL/smb-mount-wizard.git
cd smb-mount-wizard

2. Install the required system packages (Debian)

Skip this step if you're using install.sh below (step 3) - it installs all of these automatically. Only needed if you plan to run the app directly from the cloned folder instead.

sudo apt install python3-pip python3-venv nmap smbclient cifs-utils libsecret-tools samba-common-bin
sudo apt install policykit-1 || sudo apt install polkitd pkexec

The second line handles a Debian packaging change: older releases ship pkexec inside a single policykit-1 package, while Debian 13 (trixie) and newer split it into polkitd + pkexec instead. The command tries the old name first and falls back automatically.

python3-venv is only needed if you use install.sh (below) - it's what lets the installer create its own self-contained virtual environment, since Debian ships the venv module as a separate package rather than bundling it with python3.

libsecret-tools and samba-common-bin are optional - without them, credentials just aren't remembered between sessions, and LAN devices show up without a friendly hostname next to the IP, respectively - the app doesn't fail, it just does a bit less. The app's own Diagnostics tab can check for and install the rest of these after you've got it running once.

3. Install the app

Two options:

Recommended: proper install under /opt, in its own virtual environment, with a menu entry added for your account:

./install.sh

This is the Linux equivalent of installing an app "properly" instead of just running it from wherever you happened to clone it - it puts the code under /opt/smb-mount-wizard (needs sudo) and adds SMB Mount Wizard to your KDE application menu. To remove it later, run ./uninstall.sh.

Or: just run it from the cloned folder, no system-wide install:

pip install -r requirements.txt --break-system-packages
python3 main.py

If you go this route and still want a menu entry, see packaging/smb-mount-wizard.desktop - copy it to ~/.local/share/applications/ and adjust the Exec=/Path= lines to match wherever you cloned the repo.

Installing a specific release instead of the latest code

To get a known, tagged version instead of whatever is newest on the main branch:

git clone --branch v0.16.0 https://github.com/TjomekPL/smb-mount-wizard.git

See the Releases page for the full list of tagged versions and what changed in each.

Notes

• Mounting and any /etc/fstab changes go through pkexec, so you'll be prompted for your account password (not the share's) once per action.
• Mounted shares default to file_mode=0600,dir_mode=0700 - only the mounting user can read the contents locally.
• "Open without mounting" browses via smb:// (KDE's KIO/libsmbclient) rather than the kernel's cifs.ko, which some servers with mandatory SMB3 encryption don't negotiate correctly with over that path - the app tries to detect this and explain it, but if a share is already mounted, use that instead of the folder-icon button for a guaranteed working view.