Skip to main content

LUKS Tray

luks-tray is a QT-based tray utility for managing ad hoc LUKS-encrypted files: mount and unmount with ease from your Linux desktop environment.

Features

  • System tray integration - Simple click-to-mount/unmount interface for LUKS devices and files
  • Visual status indicators - Symbols mounted (▣), mounted read-only (⧈), unmounted (▽), and open-but-unmounted (‼) states
  • File container support - Add, create, and manage LUKS file containers from the tray.
  • Mount point history - Remembers previous mount locations for convenience and clarity
  • Background monitoring - Automatically detects newly inserted devices with LUKS containers
  • Password management - Optional master password to encrypt stored credentials

Quick Start

  1. Install luks-tray using pipx; e.g. pipx install luks-tray. See pipx docs.
  2. Setup passwordless sudo if not already (see notes below if needed).
  3. From a terminal:
    • run luks-tray --check-deps and install any required commands.
    • run luk-tray to ensure it finds your system tray and appears.
  4. Right-click the tray icon to see available containers. You may:
    • Insert a disk with LUKS devices to detect them automatically.
    • Add an existing or create a new encrypted file to manage it.
  5. Left-click a ▽ container to mount it; or a ▣ or ⧈ or ‼ container to unmount it.
  6. When mounting a container, enter its password and choose mount point in the dialog
    • if the app has a mount point in its history, it will fill in that mount point
    • otherwise, the app will generate a mount point in ~/Vaults
  7. Finally, for convenience when working, add luks-tray to your "auto-start" apps.

Visual Interface

The tray icon is shaped like a shield changes based on container states:

  • White Shield Icon - All containers are locked and unmounted (i.e., all data is secure).
  • Alert Shield Icon - Some containers are unlocked but unmounted (i.e., one or more anomalies).
  • Green Shield Icon - Some containers are mounted w/o any anomalies (i.e., some of the encrypted data is available)

Here is an sample menu as seen when you right-click the tray shield icon:

Sample Menu

Notes:

  • the first section shows LUKS devices, and the second shows LUKS files.

  • click a ▣ or ⧈ entry to dismount and lock a mounted, unlocked LUKS container

    • note that ▣ indicates full access; ⧈ indicates readonly
    • if busy, you are shown the PIDs and names of processes preventing dismount
  • click a ▽ entry to unlock and mount a locked LUKS container

  • click a ‼ entry to lock an unmounted, unlocked container (considered an anomaly)

  • or click of the action lines to perform the described action

  • LUKS devices must be created with other tools such as Gnome Disks.

  • LUKS files are only automatically detected in its history; when you add or create new LUKS files, they are added to the history.

  • When creating LUKS files, the default folder is ~/.Crypts.

  • When mounting LUKS files for the first time, the default folder is ~/Crypts/{basename} where {basename} is the basename of the encrypted LUKS file (less any .luks, .luks2, or .crypt suffix).

Configuration

Settings and data files are stored in ~/.config/luks-tray/:

  • History file - Stored of passwords and mount preferences; it is encrypted when the master password enabled.

  • INI file - the default .ini file looks like:

    [ui]
    show_passwords_by_default = True
    show_anomaly_alerts = True
    auto_mount_folder = ~/Vaults
    

    You can thus change

    • whether passwords are shown by default when being first entered.
    • whether ‼️ entries (i.e., anomalies) cause the tray icon to change to the alert shield.
    • where the automatically generated mount points live

Security Notes

  • Passwords are only stored when master password feature is enabled
  • History file is encrypted using the master password
  • System mount points are excluded by default to prevent interference with disk encryption
  • When creating LUKS file containers, password strength is not enforced; use due care.

Limitations

  • Not for whole disk encryption - Designed for fixed and removable partition and file containers. Thus, excludes system mount points like /, /home, /var to avoid interfering with boot-time encrypted volumes.
  • No udisks2 integration - Manages its own mount/unmount state. Mixing mounts/unmounts desktop auto-mounting tools may not produce the best results.
  • Loop device requirement - File containers require lsblk to show them as loop devices (standard on most distros)
  • Single filesystem focus - Containers with multiple filesystems are out of scope of this tool and get very limited support (i.e., mostly handling only the first filesystem).

Requirements

Additional System Utilities may be Needed

This program requires cryptsetup, fuser, and other system utilities. After install, run luks-tray --check-deps to get a report on what dependencies are found and missing. If any are missing, install those using your distro package manager.

Passwordless sudo Setup (Required)

To allow the tray app to manage LUKS containers without prompting for your password each time, configure passwordless sudo for specific commands. For example, in a terminal, run sudo visudo, and then add this line at the end of the file (replacing {yourusername} with your actual username):

{yourusername} ALL=(ALL) NOPASSWD: ALL

💡 This grants your user passwordless access to all commands. You may be able to limit it to just the luks-tray app or a subset of commands it uses (listed with --check-deps). See man sudoers for details.

A Working System Tray

It works best with DEs/WMs that offer first-class tray support, such as:

  • KDE Plasma (X11 or Waylan)
  • i3wm with polybar
  • sway with waybar (actually, quite 2nd class ... see "Workaounds for SWAY" below)

⚠️ GNOME: Requires a third-party extension (such as AppIndicator support) to show tray icons. Results may vary across GNOME versions.
⚠️ Xfce and similar lightweight DEs: Tray menus may open off-screen or be partially cut off, depending on panel layout and screen resolution.

Workarounds for SWAY

Required Workarounds for ~/.config/sway/config:

  • Environment variables: sway must be in $XDG_CURRENT_DESKTOP or $DESKTOP_SESSION

  • The user must deal with missing titlebars for moving/closing.

  • It is best to add configuration rules to ensure dialogs float:

  for_window title "luks-tray.%" floating enable, center, border normal, no_focus

Test Notes:

  • for no filesystems:
    • sudo dd if=/dev/zero of=/tmp/test_luks_container bs=1M count=100
    • sudo cryptsetup luksFormat /tmp/test_luks_container
    • sudo cryptsetup open /tmp/test_luks_container test_luks
  • for two file systems:
    • sudo pvcreate /dev/mapper/test_luks
    • sudo vgcreate test_vg /dev/mapper/test_luks
    • sudo lvcreate -L 20M -n lv1 test_vg
    • sudo lvcreate -L 20M -n lv2 test_vg
    • sudo mkfs.ext4 /dev/test_vg/lv1
    • sudo mkfs.ext4 /dev/test_vg/lv2

Metadata

Release files for luks-tray 2.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for luks-tray 2.0.5
File Size Uploaded Provenance Actions
luks_tray-2.0.5.tar.gz 82.4 kB Without provenance Details for luks_tray-2.0.5.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for luks-tray 2.0.5
File Interpreter ABI Platform Actions
luks_tray-2.0.5-py3-none-any.whl Python 3 none any Details for luks_tray-2.0.5-py3-none-any.whl

Total release size: 165.5 kB

Release files / luks_tray-2.0.5.tar.gz

Download URL luks_tray-2.0.5.tar.gz
Size 82.4 kB
Tags Source
SHA-256 checksum
How to use checksums
b93ebeb6ccf8a02e064eaa1cbe902ac8431eb3bd16cb22fb57a934f2acf42dc1
BLAKE2b-256 checksum
How to use checksums
1d0365c694f580ec7df71ac1d1b1a4c4b04e863e8655f7da48e56edc5f56bdfe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.32.4

Release files / luks_tray-2.0.5-py3-none-any.whl

Download URL luks_tray-2.0.5-py3-none-any.whl
Size 83.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
bea4fd9c604dd5040fd94d6e036966a876f274d147569e9d0e5a226d73d08023
BLAKE2b-256 checksum
How to use checksums
fb061607a95f56cf26618ae651aead961e6d2252739dc42701af1a580223f303
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via python-requests/2.32.4

Security for luks-tray 2.0.5

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page