Skip to content

Home

Jump to bottom Edit New page
Thierry Volpiatto edited this page Mar 14, 2025 · 71 revisions

Table of Contents

Requirements

Helm require an emacs version >= 25.1 starting from version 3.6.2. Helm uses few dependencies, actually only emacs-async (mandatory) and wfnames but if you install from Melpa you should not care about this. For a better experience, it is good to install all-the-icons and svg-lib but it is not mandatory. Also it is a good idea to install a good grep program like RipGrep

Install

From Straight package manager

Add this to your init file (straight-use-package 'helm), or

(use-package helm
:straight t
:config
[...])

see Straight getting started for more info.

From source

Helm needs emacs-async and wfnames (not mandatory) as dependencies, install them somewhere in your load-path.

NOTE: When installing emacs-async from sources you should install it using make and make install to ensure helm will find it when running make, otherwise you will have to specify its location from the command line, see below.

To install Helm, get the files from the helm git repo (see the tagged releases for older versions) with git (see command below) or by downloading an archive and decompressing it.

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

Then go to the resulting Helm directory and run

make

and

sudo make install

NOTE: Since helm version 2.7.0, helm wont compile with just make if you have installed emacs-async in a non standard location, in that case you will have to specify where emacs-async live on the command line, with the EMACSLOADPATH environment variable.

So after downloading, go to the resulting Helm directory and run

EMACSLOADPATH="/path/to/emacs-async:" make

Don’t forget the final “:” to not override other load-paths and use an absolute path not abbreviated, i.e /home/you/foo/bar: and not ~/foo/bar: to specify EMACSLOADPATH.

When installing from source with make && sudo make install, helm files are installed in “${PREFIX}share/emacs/site-lisp/helm/” where PREFIX is ”usr/local” by default, if your emacs is installed somewhere else specify PREFIX on command line.

As a benefit of installing from source, make install creates a symlink called helm in “${PREFIX}bin which allows you to call the script emacs-helm.sh from anywhere i.e. no need to cd in Helm directory.

NOTE: make install will NOT work on Windows system, but you can move your helm directory to your load-path e.g. /site-lisp and run make there.

From MELPA

Helm is available on 3 major package.el community-maintained repos: MELPA, NonGnu and MELPA Stable. For MELPA, Follow the instructions to set up the repository.

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

Note: Helm installation is not possible with package-vc.

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

Upgrade or recompile

Melpa

Upgrade

The only thing you have to do is to upgrade from package manager. Be sure to RESTART Emacs once upgraded. You can use M-x helm-packages which is easy to use, asynchronous etc…

Potential issues

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

To get around these errors, you are adviced to upgrade your packages asynchronously, doing this will ensure compilation is done in a clean environment. To do so please use the helm-packages interface (M-x helm-packages) which by default upgrade/install packages asynchronously.

If you don’t use the helm-packages interface, you are strongly advised to use async-bytecomp-package-mode this to compile all packages async for safety.

When some changes are made in Helm-core and those changes are used in Helm, package.el may install Helm before Helm-core which may create errors depending on changes on Helm-core e.g. New macro, renaming function or macro, changing a macro in function and vice versa etc… In this case you will have a better time uninstalling all (Helm+Helm-core), restarting Emacs and reinstalling Helm. Installing/upgrading from source doesn’t suffer from this problem.

Sources

Use make or make && sudo make install and RESTART Emacs.

Straight

Once you have called straight-pull-package of straight-pull-all, restart Emacs, straight will rebuild helm for you.

Configure

Note: In the past we had a file called “helm-config.el” that was needed for installation from source only (most people were requiring it with an installation from package which was unuseful) the file doesn’t exists anymore, therefore if you try to require it you will have an error.

If installed from emacs package manager (package.el)

You should have nothing to do, most commands should be autoloaded. However you will not have the global bindings enabled until you require helm with either require or use-package.

If installed from straight

Not much to do either, you need a straight or use-package declaration:

(straight-use-package 'helm)

Or

(use-package helm :straight t)

If installed from source

Ensure the emacs-async package is in load-path:

(add-to-list 'load-path "/path/to/emacs-async/directory")

When installed from source you have to load the helm-autoloads.el file generated by Make, (require 'helm-autoloads) is doing that for you.

add the following:

(add-to-list 'load-path "/path/to/helm/directory") ; facultative when installed with make install
(require 'helm)
(require 'helm-autoloads)

or with use-package:

(add-to-list 'load-path "/path/to/helm/directory") ; facultative when installed with make install
(use-package helm :config (require 'helm-autoloads))

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

As example you can have a look at the maintainer helm config here.

To setup specific variables from the helm session you are in, use C-h c.

You may want as well to enable helm completion everywhere in Emacs, for this use (helm-mode 1).

Now you may want to try some helm commands from the emacs menu (toolbar) or starting with e.g. C-x c C-x C-f.

Once you find some useful commands for you, bind them to a more convenient key than with the C-x c prefix.

For more complex configuration have a look at the maintainer config.

General concept

People often think helm is just something like ido but displaying completion in a vertical layout instead of an horizontal one, it is not, helm is much more powerful than that.

  • Helm is able to complete multiple lists dispatched in different sources against a pattern.
  • Helm allows executing an unlimited number of actions on candidates.
  • Helm allows marking candidates to execute chosen action against this set of candidates.
  • Helm can display its completion buffer in different window layouts and in separate frame.

However Helm is divided in two distinct categories of commands, the helm natives commands that provide a feature not existing in Emacs or a new implementation of an existing Emacs feature and the helmized commands that are Emacs native commands modified by helm-mode to provide helm completion and only that. When both are provided e.g switch-to-buffer vs helm-buffers-list you will prefer the native helm commands generally more featured (more than one action, allows marking candidates, better display etc…).

Quick Try with emacs-helm.sh

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.d/elpa/helm-<VERSION>/emacs-helm.sh

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

Note: If you have installed from Melpa, for convenience, consider creating a symlink of emacs-helm.sh to e.g ~/bin, if you have installed from source (make && sudo make install) a symlink named helm have already been created.

NOTE: For people using a non standard Elpa directory emacs-helm.sh may fail because it doesn’t find its dependency (emacs-async), here’s how you can do:

cd /your/path/to/helm
make # If not already done.
EMACSLOADPATH="../emacs-async:" ./emacs-helm.sh

But normally emacs-helm.sh should work out of the box with installations of emacs-async done with package.el, straight.el or from source with the Makefile.

Helm Completion v.s. Emacs Completion

Differences between the two often trip up new users.

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 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> or C-i lists available actions
  • C-j or C-z invokes the persistent action
  • M-SPC or C-SPC or C-@ marks a candidate
  • C-h m displays the embeded help in an org buffer without quitting helm session.
  • RET runs the first action of action list

Yanking text

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

M-n copies symbol at point to minibuffer

C-w appends word next to point to the minibuffer and advance to next word, hitting C-_ undo last insertion and rewind yank point in helm-current-buffer

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

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

linum-relative

(helm-linum-relative-mode 1) enables linum-relative in Helm. Helm buffers then display line 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

Basic scripting with emacs-helm.sh

Use emacs-helm.sh as a advanced cd command similar to broot:

hcd () {
    helm --chdir $(pwd) -nw --eval "(progn (helm-set-local-variable 'helm-full-frame t) \
(setq helm-ff-auto-update-initial-value t) \
(let ((file (read-file-name \"File: \"))) \
(if (file-directory-p file) (kill-emacs (format \"cd '%s'\" file)) (find-file file))))"
}

Add this function to .bashrc. NOTE: helm is available when installing from source (with make install).

Useful links

Contributing to the Wiki

  1. Prefer using Org mode for Wiki pages.
  2. Install the toc package to automatically generate tables of contents.
  3. Edit the Wiki.
  4. Before saving, run toc-toc.
Add a custom footer
Add a custom sidebar

Clone this wiki locally