UDISKIE(8)

📦

version 2.7.0 · 4 versions

💖 UDISKIE 💖

okay bestie, sit down, hydrate, and let me tell you about udiskie — it's section 8 of the manual and it is lowkey the most useful little gremlin on your system. 🫶

✨ NAME ✨

udiskie — automounter for removable media 💅

🌸 SYNOPSIS 🌸

udiskie [OPTIONS]

udiskie-mount [OPTIONS] (-a | DEVICE...)

udiskie-umount [OPTIONS] (-a | PATH...)

🦋 DESCRIPTION 🦋

So. udiskie is an udisks2 front-end written in python. Its whole main character purpose is automatically mounting removable media, like your CDs or your flash drives — the stuff you plug in and then immediately forget about. 🔥

It also comes with optional extras if you want them: mount notifications, a GTK tray icon, and user level CLIs for manual mount and unmount operations. And here's the tea on where your stuff ends up — the media will be mounted in a new directory under /media or /run/media/USER/, using the device name if possible. ✨

🎀 COMMON OPTIONS 🎀

these are the ones everybody shares, no drama:

-h, --help — Show help message and exit. 🙈
-V, --version — Show help message and exit.
-v, --verbose — Verbose output. (she's chatty, we love that 💬)
-q, --quiet — Quiet output. (she's giving ✨silence✨)
-c FILE, --config=FILE — Specify config file.
-C, --no-config — Don't use any config file. periodt.

🧚 SHARED MOUNT AND DAEMON OPTIONS 🧚

both the mount side and the daemon side get these, they're sharing custody:

-p COMMAND, --password-prompt=COMMAND — Password retrieval command. The string is formatted with the device attributes as keyword arguments, e.g.:

-p "zenity --entry --hide-text --text 'Enter password for {device_presentation}:'"

-P, --no-password-prompt — Disable unlocking of LUKS devices. 🔒 no unlocking, we don't know her.

👑 DAEMON OPTIONS 👑

-a, --automount — Enable automounting new devices (default). she's on it fr fr.
-A, --no-automount — Disable automounting new devices.
-n, --notify — Enable pop-up notifications (default).
-N, --no-notify — Disable pop-up notifications.
-t, --tray — Show tray icon. 👑
-s, --smart-tray — Show tray icon that automatically hides when there is no action available. iconic behaviour honestly.
-T, --no-tray — Disable tray icon (default).
-f PROGRAM, --file-manager=PROGRAM — Set program to open mounted directories. Default is 'xdg-open'. Pass an empty string to disable this feature.
-F, --no-file-manager — Disable browsing.
--terminal=PROGRAM — Set terminal command line to open mounted directories. Default is none! Pass an empty string to disable this feature.
--no-terminal — Disable terminal action.
--appindicator — Use AppIndicator3 for the status icon. Use this on Ubuntu/Unity if no icon is shown. (iykyk 😭)
--no-appindicator — Use Gtk.StatusIcon for the status icon (default).
--password-cache MINUTES — Cache passwords for LUKS partitions and set the timeout.
--no-password-cache — Never cache passwords (default).
--event-hook COMMAND — Command to execute on device events. Command string be formatted using the event name and the list of device attributes (see below), e.g.:

--event-hook "zenity --info --text '{event}: {device_presentation}'"

--no-event-hook — No notify command (default).

🌈 MOUNT OPTIONS 🌈

-a, --all — Mount all handled devices. all of them. every single one. 💅
-r, --recursive — Recursively mount cleartext partitions after unlocking a LUKS device. This will happen by default when running the udiskie daemon.
-R, --no-recursive — Disable recursive mounting (default).
-o OPTIONS, --options=OPTIONS — Set mount options.

💜 UNMOUNT OPTIONS 💜

-a, --all — Unmount all handled devices.
-d, --detach — Detach drive by e.g. powering down its physical port. bye bye 🔌
-D, --no-detach — Don't detach drive (default).
-e, --eject — Eject media from the drive, e.g CDROM. 📀
-E, --no-eject — Don't eject media (default).
-f, --force — Force removal (recursive unmounting). she's not asking. 😤
-F, --no-force — Don't force removal (default).
-l, --lock — Lock device after unmounting (default).
-L, --no-lock — Don't lock device.

🍓 EXAMPLE USAGE 🍓

Start udiskie in ~/.xinitrc:

udiskie &

Unmount media and power down USB device:

udiskie-umount --detach /media/Sticky

Mount all media:

udiskie-mount -a

Mount /dev/sdb1:

udiskie-mount /dev/sdb1

💀 CONFIGURATION 💀

okay this is the big one, stay with me. 🧚

The file .config/udiskie/config.yml can be used to configure defaults for command line parameters and customize further settings. The actual path may differ depending on $XDG_CONFIG_HOME. The file format is YAML, see https://en.wikipedia.org/wiki/YAML. And listen — if you don't want to install PyYAML, it is possible to use an equivalent JSON file with the name config.json instead. slay, options.

here's the whole annotated example config, comments and all, verbatim because I am not about to paraphrase YAML at you:

# This is an example (nonsense) configuration file for udiskie.

program_options:
  # Configure defaults for command line options

  tray:             auto    # [bool] Enable the tray icon. "auto"
                            # means auto-hide the tray icon when
                            # there are no handled devices.

  menu:             flat    # ["flat" | "nested"] Set the
                            # systray menu behaviour.

  automount:        false   # [bool] Enable automatic mounting.

  notify:           true    # [bool] Enable notifications.

  password_cache:   30      # [int] Password cache in minutes. Caching is
                            # disabled by default. It can be disabled
                            # explicitly by setting it to false

  file_manager:     xdg-open
    # [string] Set program to open directories. It will be invoked
    # with the folder path as its last command line argument.

  terminal:         'termite -d'
    # [string] Set terminal command line to open directories. It will be
    # invoked with the folder path as its last command line argument.

  password_prompt: ["gnome-keyring-query", "get", "{id_uuid}"]
    # [string|list] Set command to retrieve passwords. If specified
    # as a list it defines the ARGV array for the program call. If
    # specified as a string, it will be expanded in a shell-like
    # manner. Each string will be formatted using `str.format`. For a
    # list of device attributes, see below. The two special string values
    # "builtin:gui" and "builtin:tty" signify to use udiskie's
    # builtin password prompt.

  event_hook: "zenity --info --text '{event}: {device_presentation}'"
    # [string|list] Set command to be executed on any device event.
    # This is specified like `password_prompt`.

device_config:

  # List of device option rules. Each item can match any combination of device
  # attributes. Additionally, it defines the resulting action (see below).
  # Any rule can contain multiple filters (AND) and multiple actions.
  # Only the first matching rule that defines a given action is used.
  # The rules defined here are simply prepended to the builtin device rules,
  # so that it is possible to completely overwrite the defaults by specifying
  # a catch-all rule (i.e. a rule without device attributes).
  # Filter rules can be passed a list of values, in which case the rule is matched
  # if the attribute matches any of the values in the list.

- device_file: /dev/dm-5    # [filter]
  ignore:      false        # [action] never ignore this device
- id_uuid:                  # [filter] match by device UUID
  - 9d53-13ba               # This rule matches on either of these uids
  - 8675-309a
  options: [noexec, nodev]  # [action] mount options can be given as list
  ignore:  false            # [action] never ignore this device (even if fs=FAT)
  automount: false          # [action] do not automount this device
- id_type: vfat             # [filter] match file system type
  ignore:  true             # [action] ignore all FAT devices

- id_type: ntfs             # [filter] (optional)
  skip: true                # [action] skip all further (even builtin) rules
                            # for all matched devices, and resolve action result
                            # on parent device

- ignore:    true           # never mount/unmount or even show this in the GUI
  automount: false          # show but do not automount this device
  options: []               # additional options to be passed when mounting

- id_uuid: ...              # [filter] match device by UUID
  keyfile: /path/to/keyfile # [action] use keyfile to unlock a luks encrypted
                            # device, bypassing the password prompt

mount_options:              # [deprecated] do not use
ignore_device:              # [deprecated] do not use

notifications:
  # Customize which notifications are shown for how long. Possible
  # values are:
  #   positive number         timeout in seconds
  #   false                   disable
  #   -1                      use the libnotify default timeout

  timeout:          1.5     # set the default for all notifications

  # Specify only if you want to overwrite the default:
  device_mounted:   5       # mount notification
  device_unmounted: false   # unmount notification
  device_added:     false   # device has appeared
  device_removed:   false   # device has disappeared
  device_unlocked:  -1      # encrypted device was unlocked
  device_locked:    -1      # encrypted device was locked
  job_failed:       -1      # mount/unlock/.. has failed

quickmenu_actions: [mount, unmount, unlock, terminal, detach, delete]
  # List of actions to be shown in the quickmenu or the special value 'all'.
  # The quickmenu is shown on left-click if using flat menu type.

notification_actions:
  # Define which actions should be shown on notifications. Note that there
  # are currently only a limited set of actions available for each
  # notification. Events that are not explicitly specified show the default
  # set of actions. Specify an empty list if you don't want to see any
  # notification for the specified event:

  device_mounted:   [browse]
  device_added:     [mount]

icon_names:
  # Customize the icon set used by the tray widget. Each entry
  # specifies a list of icon names. The first installed icon from
  # that list will be used.

  media:   [drive-removable-media, media-optical]
  browse:  [document-open, folder-open]
  terminal: [terminal, terminator, xfce-terminal]
  mount:   [udiskie-mount]
  unmount: [udiskie-unmount]
  unlock:  [udiskie-unlock]
  lock:    [udiskie-lock]
  eject:   [udiskie-eject, media-eject]
  detach:  [udiskie-detach]
  delete:  [udiskie-eject]
  quit:    [application-exit]

💡 All keys are optional. Reasonable defaults are used if you leave them unspecified. so like. you can't really mess this up bestie 🫶

🦋 DEVICE ATTRIBUTES 🦋

okay so some of the config entries be using Device attributes. here's the list that's currently out there, BUT — and she said this not me — there is no guarantee that they will remain available. so like, enjoy them while they're here bestie 😭

fr fr, that caveat is straight from the source. don't come for me if your config breaks in three years.

is_drive — no hint or example given in the original, so I'm not about to invent one 💅
is_block — same deal, no hint, no example, moving on
is_partition_table — no hint/example provided
is_partition — no hint/example provided
is_filesystem — no hint/example provided
is_luks — no hint/example provided
is_loop — no hint/example provided
is_toplevel — no hint/example provided
is_detachable — no hint/example provided
is_ejectable — no hint/example provided
has_media — no hint/example provided
device_file — block device path, e.g. "/dev/sdb1"
device_presentation — display string, e.g. "/dev/sdb1"
device_size — block device size
device_id — unique, persistent device identifier
id_usage — e.g. "filesystem" or "crypto"
is_crypto — no hint/example provided
is_ignored — no hint/example provided
id_type — e.g. "ext4" or "crypto_LUKS"
id_label — device label
id_uuid — device UUID
is_luks_cleartext — no hint/example provided
is_external — udisks flag HintSystem=false
is_systeminternal — udisks flag HintSystem=true
is_mounted — no hint/example provided
mount_paths — list of mount paths
mount_path — any mount path
is_unlocked — no hint/example provided
in_use — device or any of its children mounted
should_automount — no hint/example provided
ui_label — no hint/example provided
loop_file — file backing the loop device
setup_by_uid — user that setup the loop device
autoclear — automatically delete loop device after use
symlinks — no hint/example provided
drive_model — no hint/example provided
drive_vendor — no hint/example provided
drive_label — no hint/example provided
ui_device_label — no hint/example provided
ui_device_presentation — no hint/example provided
ui_id_label — no hint/example provided
ui_id_uuid — no hint/example provided

🌈 SEE ALSO 🌈

the way this is literally the shortest section and it still ate 💅 go read the udisks page too, iykyk 🫶

💖 CONTACT 💖

if you hit a problem, got a general question, or you're like "bestie this needs a new feature", you can use the github issues. and if you don't have github, or you just don't vibe with it, you can reach out by email instead:

https://github.com/coldfix/udiskie/issues
thomas@coldfix.de

no cap, both of those are valid ways to slide into the maintainer's inbox 🎀

and that's the whole page babes, you made it to the end 🥳 this was udiskie, part of UDISKIE(8), dated 08/20/2026. go forth and mount responsibly, mwah 💋✨

📦 where this page comes from

fedora 44: udiskie 2.7.0-1.fc44 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms