Mak Kolybabi edited this page Jan 24, 2017 · 6 revisions

Table of Contents



Helm is available on two major package.el community-maintained repos: MELPA and MELPA Stable. Follow the instructions to set up the MELPA (Stable) repository.

Install Helm with M-x package install RET helm RET.

Note: always restart Emacs after reinstalling Helm (or other packages) for the updates to take effect.

Potential issues

Helm upgrades from MELPA encountered errors because of the way the Emacs package manager fetched and compiled updates for existing packages.

To get around these errors, Helm has emacs-async as a dependency. emacs-async forces compilation in a clean environment, which resolves the compilation errors.

From source

Helm needs popup-el as a dependency, but we recommend installing emacs-async, since emacs-async has other benefits as well, both for Helm and other packages. See the FAQ for more information.

To install, get the files from the Git repo (see the tagged releases for older versions):

git clone https://github.com/emacs-helm/helm

After downloading, go to the Helm directory and run make.


If installed via the Emacs package manager, add the following to your init file:

(require 'helm-config)

If installed from source, add the following:

(add-to-list 'load-path "/path/to/helm/directory")
(require 'helm-config)

This will do same basic preparation (load autoloads for example), but it will not load Helm or turn on the Helm minor mode.

For further configuration like changing bindings in the helm-map you will likely want to use a delayed method like with-eval-after-load to avoid loading all of Helm at startup.

Quick Try

To try Helm with a default configurations in a minimal Emacs, run the provided emacs-helm.sh script in Helm’s installation directory. If installed through the Emacs package manager,


emacs-helm.sh should also be used when reporting bugs.

Note: for convenience, consider creating a symlink of emacs-helm.sh.

Helm Completion v.s. Emacs Completion

This different has tripped up new users in ways involving

Emacs completion is based on the minibuffer. Helm completion is based on the completion window.

In default Emacs, interactivity happens in the minibuffer.

  • Typing new characters filters candidates in the minibuffer.
    • <tab> may try to complete the typed characters with a valid candidate.
  • Hitting RET selects the current candidate from the minibuffer.

In Helm, interactivity happens in the completion window, not the minibuffer

  • Typing new characters filters candidates in the completion window.
    • Type until the desired candidate is highlighted, or navigate to it using C-n.
  • Hitting RET selects the currently highlighted item in the completion window.

Helm interaction model

Helm’s interactivity makes the <tab> key redundant for completion because the selection candidates are already made visible in the Helm completion window. So, tab completion is not supported. In Helm, <tab> is used to view available actions to be taken on a candidate.

Because the <tab> key is so ingrained in the muscle memory of long-time Emacs users, transition to Helm’s interactive model requires:

  • A conscious visual adjustment to look at the completion window, and
  • A conscious mental adjustment to avoid using the <tab> key for completion and go straight to <RET> key to select a candidate. Helm’s approach to completion is provides better visual cues, takes fewer keystrokes, and is much faster.

General Helm Commands

Helm’s functionality needs only a few general key bindings as shown below. These are also documented in the mode line.

  • <tab> lists available actions
  • C-z invokes the persistent action
  • M-SPC marks a candidate
  • C-h m shows other key bindings besides those shown in the modeline

Look in the Helm buffer’s header for any other active key bindings.

Yanking text

Yank symbol at point from helm-current-buffer (i.e. buffer where a helm command was invoked):

M-n copies yanked symbol to minibuffer

C-w appends word next to point to the minibuffer

Preconfigured Helm Commands

  • helm-command-prefix-key is the prefix for the preconfigured helm menu.
  • C-x c is the default key binding for helm-command-prefix-key.
  • helm-M-x and then type “helm” to discover Helm commands.
    • This is the same as running helm-command-prefix-key followed by M-x.
  • The Helm > All commands menu item is another way to discover helm commands.
    • It runs helm-execute-helm-command.
  • helm-command-prefix-key followed by any regular Emacs key invokes the Helm version of the same command.
    • E.g. helm-M-x for M-x.

To run the helm version of a command with a key binding, set it in your init file as follows:

(global-set-key (kbd "M-x") 'helm-M-x)

Show Helm Commands

  • C-h m shows Helm commands and currently active key bindings.

Browse Other Tools

  • Invoke M-x, then type “helm” to browse other Helm tools.


helm-mode enables Helm completion globally for any Emacs command using completing-read or read-file-name.

helm-mode completes with completion-at-point and implements completion-in-region-function for completing-read-multiple for Emacs 24.4 and later.

Helm provides generic functions for completions to replace tab-completion in Emacs with no loss of functionality. To use Helm’s generic functions, first set them in your init file, e.g.:

(global-set-key (kbd "M-x") #'helm-M-x)
(global-set-key (kbd "C-x r b") #'helm-filtered-bookmarks)
(global-set-key (kbd "C-x C-f") #'helm-find-files)

Then enable helm-mode with:

(helm-mode 1)

Or, enable helm-mode interactively with M-x helm-mode.

Customize helm-mode

To customize the completion interface or disable completion for specific commands in helm-mode, edit helm-completing-read-handlers-alist. See C-h v helm-completing-read-handlers-alist for details.

Use helm-mode and ido-mode

To use Ido for some commands and Helm for others, do not enable ido-mode. Instead, customize helm-completing-read-handlers-alist to specify which command uses Ido.

For example, suppose we want find-file-read-only to use Ido and find-file to use Helm. Then:

  1. In your init file, turn on helm-mode.
  2. In the helm-mode customize group, add a key to helm-completing-read-handlers-alist for find-file-read-only with value ido, i.e.
(find-file-read-only . ido)

With helm-mode active, to use Emacs default completion instead of either Helm or Ido, use nil for the key value:

(find-alternate-file . nil)

Other Useful Extensions

MELPA and other repositories have many useful extensions, some of which are redundant as Helm already provides them. Review if they already exist as part of the default Helm package before downloading new extensions.

Helm With Other Emacs Extensions


(helm-linum-relative-mode 1) enables linum-relative in Helm. Helm buffers then display nine numbered candidates before and after the current candidate (highlighted line). C-x <n> jumps to n lines before, before, and C-c <n> jumps to n lines after, the current candidate.

Helm Workflow for Files, Directories and Buffers

The new Helm workflow uses fewer buffers. Whereas the old workflow opened many Dired buffers stacked in the workspace, the new approach uses virtual Dired buffers without cluttering the buffer list with many Dired buffers. The decluttering of buffers also helps with running helm-locate without conflicts; there’s also less need to resort to other workarounds, such as running helm-multi-files.

The new approach uses helm-find-files as the starting point, never opens Dired buffers yet provides easy access to common Helm commands, such as grep, locate, find, etc. These Helm commands, moreover, are not limited to the current directory because Helm now allows marking files in other directories before running the commands.

Other quick jumping off features of helm-find-files:

  • C-x C-d (helm-browse-project) shows buffers and files in the project.
  • C-c C-d with prefix argument shows files in this directory and its subdirectories recursively.

When using helm-ls-git and helm-ls-hg, files under version control have a corresponding backend indicator.

  • C-x C-b to switch back to the resumed Helm sources.
  • M-p to access history of helm-find-files
  • C-c h to access the full history of files (file-name-history)
  • C-x C-f switches back to helm-find-files

Useful links

Contributing to the Wiki

  1. Prefer using Org mode for Wiki pages.
  2. Install the toc-org package to automatically generate tables of contents.
  3. Edit the Wiki.
  4. Before saving, run toc-org-insert-toc.
    • Consider adding something like the following to before-save-hook to do this automatically:
(defun *-org-insert-toc ()
  "Create table of contents (TOC) if current buffer is in
  (when (= major-mode 'org-mode)