{"id":31663431,"url":"https://github.com/markhedleyjones/dmenu-extended","last_synced_at":"2026-02-08T06:14:14.283Z","repository":{"id":2190380,"uuid":"14784108","full_name":"markhedleyjones/dmenu-extended","owner":"markhedleyjones","description":"An extension to dmenu for quickly opening files and folders.","archived":false,"fork":false,"pushed_at":"2025-10-02T13:02:17.000Z","size":1050,"stargazers_count":392,"open_issues_count":32,"forks_count":34,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-10-04T03:42:17.169Z","etag":null,"topics":["dmenu","python","rofi","systemd","tiling-window-manager"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markhedleyjones.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2013-11-28T18:37:01.000Z","updated_at":"2025-09-04T21:05:07.000Z","dependencies_parsed_at":"2024-01-14T16:08:59.660Z","dependency_job_id":"b279f313-6f34-43aa-aa5e-b5a9b0ba05f6","html_url":"https://github.com/markhedleyjones/dmenu-extended","commit_stats":{"total_commits":349,"total_committers":24,"mean_commits":"14.541666666666666","dds":0.4355300859598854,"last_synced_commit":"c97039d3659b366d9701850eafe5d0bb27f74115"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/markhedleyjones/dmenu-extended","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markhedleyjones%2Fdmenu-extended","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markhedleyjones%2Fdmenu-extended/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markhedleyjones%2Fdmenu-extended/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markhedleyjones%2Fdmenu-extended/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markhedleyjones","download_url":"https://codeload.github.com/markhedleyjones/dmenu-extended/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markhedleyjones%2Fdmenu-extended/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278838434,"owners_count":26054720,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dmenu","python","rofi","systemd","tiling-window-manager"],"created_at":"2025-10-07T20:01:50.747Z","updated_at":"2026-02-08T06:14:14.275Z","avatar_url":"https://github.com/markhedleyjones.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"\u003cimg src=\"https://travis-ci.org/MarkHedleyJones/dmenu-extended.svg?branch=master\" alt=\"build:passed\"\u003e\n\n# dmenu-extended\n\nAn extension to the original [dmenu](http://tools.suckless.org/dmenu/) allowing super fast access to your files, folders, and programs. dmenu-extended has support for plugins, command aliasing, file filtering, and customisation. You can also use dmenu-extended with [rofi](https://davatorium.github.io/rofi/)!.\n\n## See it in action\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.github.com/markhedleyjones/dmenu-extended/master/docs/demo.gif\" alt=\"Dmenu-extended demo\"/\u003e\n\u003c/p\u003e\n\n## Feature Summary:\n\n- Indexes the files and folders you specify\n- Built in support for plugins (internet search, sudo, system package management)\n- Systemd integration for cache automatic rebuilding\n- Ability to swap the menu to Rofi\n- Support for scanning alias files (e.g. .bashrc)\n\n## Installation\n\n### Dependencies\n\n- **Python** - version 3.6 or higher\n- **dmenu** - version 4.5 or later\n\nQuick dependency install:\n\n- **Ubuntu** - `sudo apt-get install suckless-tools`\n- **Arch** - `sudo pacman -S dmenu`\n- **Fedora** - `sudo dnf install dmenu`\n\n### Install Method 1: PIP (recommended)\n\n```bash\nsudo pip3 install --upgrade dmenu_extended\n```\n\nAlternatively, omit `sudo` from the above command to install dmenu-extended only for the current user.\n\nTo uninstall dmenu-extended, run `sudo pip3 uninstall dmenu_extended`.\nNote that if dmenu-extended was installed without `sudo` (or root), the uninstall command should also be run without `sudo` (or root).\n\n### Install Method 2: Install from Source\n\nDependencies:\n\n- `python3-setuptools`\n\nClone this repository using `git`, or download the zip file and extract its contents.\nFrom within the extracted folder, **either** execute `setup.sh` or, execute the following commands manually:\n\nBuild the package with:\n\n```bash\npython3 -m build --wheel\n```\n\nThen to install the package, _choose one_ of the following two options:\n\n```bash\nsudo pip3 install --upgrade dist/dmenu_extended-*-py3-none-any.whl\n```\n\nAlternatively, omit `sudo` from the above command to install dmenu-extended only for the current user.\n\n### Method 3: Install via AUR\n\nAn AUR package is available here: [dmenu-extended-git](https://aur.archlinux.org/packages/dmenu-extended-git/).\n\n## Usage\n\n### Create a keybinding\n\nTest that the new menu has been installed by running `dmenu_extended_run` from your terminal. **NOTE:** The first run will be slow as it is set to scan you home folder recursively to build the cache.\n\nThe most productive way to use dmenu-extended is to bind the command `dmenu_extended_run` to an easy to reach key combo. The way in which you do this will be different depending on your desktop environment but here is a brief list.\n\n#### Ubuntu (Unity), Debian (Gnome), Mint (Cinnamon)\n\n1. Open **System settings** -\u003e **Keyboard** -\u003e **Shortcuts**\n2. Click **Custom shortcuts** and then the **+** (_add custom shortcut_) to add a new command\n3. Enter \"dmenu_extended\" as the name\n4. Enter \"dmenu_extended_run\" as the command and click apply\n5. Click next _disabled_ (_unassigned_)\n6. Press the desired combination of keys (e.g. Alt+Enter)\n\n#### Tiling window managers\n\nIf you use a tiling window manager, you may already have a key-combination bound to launch dmenu (i.e. Ctrl+P). Edit your window managers configuration file to launch `dmenu_extended_run` instead.\n\n### Advanced keybindings\n\n`dmenu_extended_run` supports automated menu item selection via argument passing. If, for example, you frequently use the 'Internet Search' plugin with a particular search provider, you may want a binding that takes you directly to that provider.\nTo do this you might bind the following command to an alternate key combination:\n\n`dmenu_extended_run \"-\u003e Internet search: \" \"Wikipedia\"`\n\nThe arguments must be written exactly as they would appear in the menu. Any number of arguments can be passed and each will be executed in the order they are passed. Each item represents one item selection from a menu. Remember to quote each item so they are passed to the menu correctly.\n\n## Configuration\n\nMenu configuration is contained in a JSON formatted file found at `~/.config/dmenu-extended/config/dmenuExtended_preferences.txt` that controls the appearance and functionality of the menu. This file is also accessible from the `-\u003e Menu configuration` submenu as `* Edit menu preferences`\n\nFunctions of the items are as follows.\n\n- `\"valid_extensions\"` list of file extensions of files to include in the cache\n- `\"watch_folders\"` list of base paths to recursively search through for items to include\n- `\"follow_symlinks\"` boolean option controlling whether to follow a link while scanning\n- `\"ignore_folders\"` list of paths to be excluded from the cache\n- `\"global_ignore_folders\"` names of folders to exclude from cache (regardless of location)\n- `\"scan_hidden_folders\"` boolean value controlling whether to enter hidden folders when scanning\n- `\"include_hidden_files\"` boolean value controlling whether to include hidden files in the cache\n- `\"include_hidden_folders\"` boolean value controlling whether to include hidden folders in the cache\n- `\"include_items\"` list of extra items to include in the cache\n- `\"exclude_items\"` list of items to be excluded from the cache\n- `\"include_binaries\"` add items found in the system path\n- `\"filter_binaries\"` boolean that causes binaries not associated with destkop applications (those having a .desktop file) to be omitted from the cache (e.g. `cp`, `mv`)\n- `\"include_applications\"` add items found under /usr/share/applications\n- `\"alias_applications\"` alias applications with their intended names\n- `\"path_aliasFile\"` path to a file containing aliases (e.g. ~/.bash_aliases)\n- `\"abbreviate_homedir\"` abbreviate $HOME as `~` for files \u0026 folders\n- `\"frequently_used\"` the number of your most frequently used commands to show at the top of the menu\n- `\"alias_display_format\"` how to format aliased commands (e.g. `\"{name} ({command})\"`)\n- `\"path_shellCommand\"` path to use for creating terminal helper script (e.g. \"~/.dmenuEextended_shellCommand.sh\")\n- `\"menu\"` executable to open the menu (dmenu)\n- `\"menu_arguments\"` list of parameters to launch the menu with\n- `\"fileopener\"` application to handle opening files\n- `\"filebrowser\"` application to handle opening folders\n- `\"webbrowser\"` application to handle opening urls (web browser)\n- `\"terminal\"` terminal emulator application\n- `\"terminal_editor\"` application used to edit files directly in the terminal\n- `\"indicator_submenu\"` symbol to indicate a submenu item in the cache\n- `\"indicator_edit\"` symbol to indicate an item will launch an editor in the cache\n- `\"indicator_alias\"` symbol to indicate an aliased command in the cache\n\nAdding the item `\"\"` to `\"valid_extensions\"` will cause files with no extension to be included in the cache.\nAdding the item `\"*\"` to `\"valid_extensions\"` will cause **all** files to be included in the cache.\n\n### Rebuild the cache from terminal\n\nIt is possible to rebuild the cache from the terminal by running:\n\n    dmenu_extended_cache_build\n\nYou could run this script directly to rebuild your cache or call it from [cron](http://en.wikipedia.org/wiki/Cron).\nDmenu has [systemd](http://en.wikipedia.org/wiki/Systemd) integration so you can set it rebuild your cache every 20 mins from the settings menu within dmenu-extended.\n\n### Background cache rebuild with Systemd\n\nAfter installing dmenu-extended, a background updater service can be enabled.\nThis will periodically update the cache in the background every 20 minutes.\nTo install the background service, run:\n\n```bash\ndmenu_extended_install_systemd_service\n```\n\nAlternative intervals can be specified by passing the `--interval-interval-mins [MINS]` argument and specifying the interval in minutes.\nThe service can then be enabled and disabled in the `-\u003e Settings` menu of dmenu-extended.\n\n### Background cache rebuild with Incron\n\nYou can also rebuild the cache everytime a file or folder is being created, deleted or moved from or to the monitored path.\nHave [Incron](https://wiki.archlinux.org/index.php/Incron) up and running. Edit your incrontab `incrontab -e` and add following line:\n\n    \u003cPATH_TO_MONITOR\u003e  IN_CREATE,IN_DELETE,IN_MOVE     \u003cPATH_DMENU_EXTENDED_CACHE_BUILD\u003e\n\nEnter the path of _dmenu_extended_cache_build_, you can find this by running `which dmenu_extended_cache_build`. All paths must be absolute! Check out incrontab(5) for more event symbols.\n\n### Rebuild cache via pacman hook\n\nYou can update your application cache after installing/uninstalling a package via a [pacman hook](https://wiki.archlinux.org/index.php/Pacman#Hooks) for immediate access/removal.\nCreate a file `/usr/share/libalpm/hooks/dmenu-cache-rebuild.hook`:\n\n```\n[Trigger]\nType = Package\nOperation = Install\nOperation = Remove\nTarget = *\n\n[Action]\nDescription = Rebuilds Cache of dmenu-extended after package installation or removal\nWhen = PostTransaction\nExec = /usr/bin/sudo -u \u003cUSER\u003e /usr/bin/dmenu_extended_cache_build\nDepends = dmenu-extended-git\n```\n\nYou need to execute the rebuild command via `sudo -u \u003cUSER\u003e`, because pacman runs as root and would therefore not update userfiles.\n\n## Running Dmenu-extended with Rofi\n\nEnsure you have Rofi installed and edit the following two configuration options as so:\n\n    \"menu\": \"rofi\",\n    \"menu_arguments\": [\n      \"-dmenu\",\n      \"-i\"\n    ],\n\nYou may also need to add\n\n    \"prompt\": \"Open\",\n\nto remove the extra colon depending on your Rofi version.\n\n### Copying entries to clipboard with Rofi\n\nWhen using Rofi, you can configure a custom key binding to copy the currently selected menu entry to the clipboard instead of executing it. This requires:\n\n1. A clipboard tool installed (`wl-copy` for Wayland, or `xclip`/`xsel` for X11)\n2. Rofi configured with a custom key binding\n\nTo enable this feature, add the `-kb-custom-1` argument to your `menu_arguments`:\n\n```json\n\"menu\": \"rofi\",\n\"menu_arguments\": [\n  \"-dmenu\",\n  \"-i\",\n  \"-kb-custom-1\",\n  \"Alt+c\"\n],\n```\n\nNow when you press Alt+C (or whatever key you bind), the selected entry will be copied to your clipboard and dmenu-extended will exit. You can then paste the entry elsewhere.\n\n**Note:** This feature is only available when using Rofi. Standard dmenu does not support custom key bindings. Some key combinations like `Control+c` are already bound by Rofi and cannot be used for custom bindings.\n\n## Advanced usage\n\nDmenu-extended understands the following modifier characters when entering a special command:\n\n1. **+** (plus) - Manually add an entry to the cache\n2. **-** (minus) - Remove a manually added entry from the cache\n3. **:** (colon) - Open with\n4. **@** (at) - Open in default terminal editor\n5. **;** (semi-colon) - Execute in terminal\n\nThese modifiers are entered into the menu; examples follow.\n\n### **+** (plus) - Manually add an entry to the cache\n\nIf there is something you wish to run that isn't in the menu then you can add it by prepending with a +.\n\n- `+htop;` adds htop to the cache.\n- `+libreoffice` adds libreoffice to the cache.\n- `+http://youtube.com` adds a link to Youtube to the cache.\n\nOnce added these commands are stored in the preferences file (see general configuration) and will persist upon a rebuild of the cache. These items can also be manually edited within this file.\n\n#### Built-in support for aliases\n\nIn addidion to adding items manually, dmenu_extended allows the addition of a more descriptive label for a stored command.\nFor instance:\n\n- `+htop;#View running processes` displays as `# View system processes (htop)`\n- `+libreoffice --writer#Writer` displays as `# Writer (libreoffice --writer)`\n- `+http://youtube.com#Youtube` displays as `# Youtube (http://www.youtube.com)`\n\n### **-** (minus) - Remove a manually added entry from the cache\n\nThis applies to items that have previously saved to the store. If the item is not found in the store you will be given the chance to add it.\n\n### **:** (colon) - Open with\n\nThere are a few different ways to use the colon operator, summarised by example below. In these examples `gedit` is the name of a text editing application.\n\n- `gedit:` - Use gEdit to open a file. A list of all files and folders will be returned to select from.\n- `gedit:.txt` - Use gEdit to open a text file. A _filtered list_ containing only text files will be shown to select from.\n- `/home/me/Documents/writing.txt:` - Open this file using... Returns a list of applications to launch the given file\n- `/home/me/Documents/writing.txt:gedit` - Open this file with gedit.\n- `gedit:/home/me/Documents/writing.txt` - Open this file with gedit.\n\n### **@** (at) - Open in terminal editor\n\nSuffix to open the chosen file inside the preferred editor in a terminal window. Default editor is set to `vim`, but it can be changed in the preferences (`\"terminal_editor\"`). The terminal window is closed as soon as the application is exited.\nFor instance:\n\n- `/home/me/Documents/writing.txt@`\n\n### **;** (semi-colon) - Execute in terminal\n\nDmenu-extended doesn't know when the application you enter needs to be executed in a terminal window. To tell dmenu-extended to launch the following in a terminal, append a semi-colon to the end. Once the terminal program has exited the terminal will close.\n\nFor example,\n\n- `htop;` - Launches htop in a terminal window. Without the semi-colon nothing would happen.\n- `alsamixer;` - Launches the ALSA sound volume manager in a terminal. Without the semicolon nothing would happen.\n\n#### Holding the terminal open on exit\n\nBy using two semicolons (`;;`) at the end of a command the terminal window will remain open once the executed command has completed. This is useful for running programs like `inxi` that exit on completion. You'll want to use this if you see your program flash up and disappear before you get a chance to see the output.\n\n### Loading an alias file\n\nIf you have an aliases file (for example ~/.bash_aliases or ~/.zsh_aliases) that you would like loaded into dmenu-extended, set it's path in the `\"path_aliasFile\"` field in of the preferences. Aliased items found in that file will show up in the menu once the cache has been rebuilt.\n\n### Controlling aliased command formatting\n\nBy default, all aliased commands are displayed prefixed without a prefix and no indication of the command being launched is given (for example `ff`). If you would prefer to have the aliased command appear with a prefix and some indication of what the command will launch (e.g. `# ff (firefox)`) - make the following alterations to your preferences file and rebuild the cache.\n\n- `\"indicator_alias\": \"\"` -\u003e `\"indicator_alias\": \"#\"`\n- `\"alias_display_format\": \"{name}\"` -\u003e `\"alias_display_format\": \"{name} ({command})\"`\n\n### Using a password helper for sudo commands\n\nPassword helper programs, such as zenity, can be used to prompt the user for a password outside of a terminal process whenever a password is required. Getting one setup requires creating a small bash script and configuration file. The following instructions step you through using zenity as the password helper program.\n\n1. Check you have zenity installed by running `whereis zenity`. You should see something like /usr/bin/zenity amongst other paths.\n2. Fill the password helper script `sudo nano /usr/local/bin/zenity_askpass` with:\n\n```\n#!/bin/bash\nzenity --password --title=\"Sudo password prompt\"\n```\n\n3. Make the askpass script executable by running `sudo chmod +x /usr/local/bin/zenity_askpass`\n4. Create/edit the sudo configuration file `sudo nano /etc/sudo.conf` and make sure it contains the line `Path askpass /usr/local/bin/zenity_askpass`\n\nTest the configuration by running a sudo command via dmenu-extended (e.g., `sudo gedit`). You should be prompted grapically for the password before the program opens.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://raw.github.com/markhedleyjones/dmenu-extended/master/docs/sc-password.png\" alt=\"Password manager screenshot\"/\u003e\n\u003c/p\u003e\n\n## Contributing\n\nAny sort of contribution is welcome, for example:\n\n- Helping out people who have [Issues](https://github.com/MarkHedleyJones/dmenu-extended/issues)\n- Writing tests\n- Improving code\n- Writing [plugins](https://github.com/MarkHedleyJones/dmenu-extended-plugins)\n- Updating documentation\n\nFor those looking to improve the code, pull-requests should follow the project's formatting standards. Only Python3 is currently supported.\n\n## Code Formatting\n\n### Python\n\nThis project uses [Ruff](https://github.com/astral-sh/ruff) for Python code formatting and linting with default settings.\n\nTo format and lint Python code:\n\n```bash\nruff format src/ tests/\nruff check --fix src/ tests/\n```\n\n### Shell Scripts\n\nShell scripts are formatted with [shfmt](https://github.com/mvdan/sh) using default settings.\n\nTo format shell scripts:\n\n```bash\nshfmt -w *.sh\n```\n\n### Automated Formatting Checks\n\nTo check all formatting (Python and shell):\n\n```bash\n./test.sh --lint\n```\n\nThis will use local tools if available, or fall back to Docker if needed.\n\n## Acknowledgements\n\n- **Alad** from the [CrunchBang forums](http://crunchbang.org/forums/viewtopic.php?id=36484) for advice on packaging.\n- **Head_on_a_Stick** also from the [CrunchBang forums](http://crunchbang.org/forums/viewtopic.php?id=36484) for advice on packaging.\n- [**EDI9999**](https://github.com/edi9999) for performance improvements to cache scanning.\n- **Pandya** from [this stackexchange answer](https://unix.stackexchange.com/a/254073) for infomation on how to set-up a password helper\n- [**nanobecquerel**](https://github.com/nanobecquerel) for improving systemd integration\n- [**fat-fighter**](https://github.com/fat-fighter) for bug fixes and solving GitHub issues\n- [**vestingz**](https://github.com/vestingz) for Incron and pacman integration.\n- [**ZappaBoy**](https://github.com/ZappaBoy) for improving alias/shell integration\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkhedleyjones%2Fdmenu-extended","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkhedleyjones%2Fdmenu-extended","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkhedleyjones%2Fdmenu-extended/lists"}