Table of Contents
- Getting Started
- Helm Applications
- Recommended Helm extensions
- Known issues
- Bugs & Improvements
- Getting help
Helm is an Emacs framework for incremental completions and narrowing
selections. It helps to rapidly complete file names, buffer names, or
any other Emacs interactions requiring selecting an item from a list of
Helm is a fork of
anything.el, which was originally written by Tamas
Patrovic and can be considered to be its successor.
Helm cleans the
legacy code that is leaner, modular, and unchained from constraints of
Helm requires Emacs-24.3 or later versions.
Helm installs async package as a dependency when Helm is installed using MELPA.
Helm installation from the git source repository does not include async. The async package is recommended for smooth asynchronous file and dired operations in Helm.
Quick install from git
helmrepository to some directory:
$ git clone https://github.com/emacs-helm/helm.git /path/to/helm/directory
asyncrepository to some directory (facultative)
$ git clone https://github.com/jwiegley/emacs-async.git /path/to/async/directory
;; If async is installed (add-to-list 'load-path "/path/to/async/directory") (add-to-list 'load-path "/path/to/helm/directory") (require 'helm-config)
NOTE: Installing helm using git and make is the safest way.
To quickly run
helm, launch this script from helm directory:
Also use the same script above for bug reporting.
NOTE: This script does not work on Windows systems.
Install from Emacs packaging system
Helm can also be installed from MELPA repository at http://melpa.org/. No further configuration is necessary to run helm other than perhaps a one-line entry in the Emacs init file:
WARNING: Helm upgrades from MELPA repository encountered errors because of the way package.el fetched and compiled updates for existing packages. To get around these errors, Helm adds Async as a dependency package install. Async forces compilation in a clean environment, which solves those compilation errors. Since async has other benefits as well, both for Helm and other packages, we recommend installing async even for Helm installs using git. See FAQ for details.
Note: Restart Emacs for Helm updates from MELPA repositories to take effect.
Note to Linux Distributions Maintainers
Only the extensions in the github emacs-helm repository are supported.
Debian and Ubuntu
Users of Debian 9 or later or Ubuntu 16.04 or later may simply
apt-get install elpa-helm (or
apt-get install elpa-helm-core; see
Installing just the helm-core package
helm-core package is available on MELPA for
third party packages that depend on helm libraries. These packages
should require helm as follows:
Requiring helm builds and runs helm code necessary for multiple regexp and fuzzy matching. See helm wiki for details.
Warning about alternate installation methods
Installation methods that circumvent
helm-config are known to fail
if the careful safeguards are not implemented in the hacks.
For minimal helm configuration, run the start-up script
and then see the file
The full configuration I (the helm maintainer) use is here.
Also see helm customizable variables with the customize interface.
helm-mode will enable helm for many features of emacs
For pre-configured Emacs installs, such as Emacs Prelude, helm is built-in with no additional configuration steps necessary for using helm.
M-x helm-M-x RET helm- lists helm commands ready for narrowing and selecting.
To bind to
(global-set-key (kbd "M-x") 'helm-M-x)
In any helm session (after
C-h m pops a general info buffer about helm
C-c ? pops a special info buffer of the current helm command
Not all helm commands have specialized info buffers. Look for
in the mode-line.
C-h m is shown for any command that does not have
a specialized info buffer.
Use these embedded Info screens first before reporting bugs.
M-x helm-mode to enable helm completion for common Emacs commands
C-x C-f, etc...). Note that the helm functionality
enabled through helm-mode comes from a generic implementation and does
not include all helm features available through equivalent
helm-specific commands. For example,
helm-M-x has more features than
helm completion through
To make helm-mode start with Emacs init file:
To discover helm commands, look at helm menu item in Emacs menu.
Another way to discover helm commands: run the shell script:
./emacs-helm.sh and then look in the scratch buffer.
accepts emacs command line options.
emacs-helm.sh -h opens an Info
screen with more details.
Helm contains many features, some of which are easier to follow
visually. Here is a demo of
helm-buffers-list used with
helm-moccur. Demo starts with
Eval: START in the minibuffer.
*Cselects the C buffers.
*Tclin the demo selects TCL buffers, then with
*Cswitches back to C buffers.
- For buffers containing the string "crash", the demo adds a space,
then the pattern
- Matching buffers are then handed over to
moccurwith its own Helm interface. The demo shows switching to a single file,
kexec.c. Multiple selections can be made with
- Adding characters to the pattern gradually filters (narrows) the
available candidates. By adding
memory, the buffers shown now include those buffers with "crash" and "memory".
With more pattern matching, candidates are narrowed down from the initial 253 buffers to 12 as shown in the modeline.
Creating custom helm sources
(helm :sources (helm-build-sync-source "test" :candidates '(foo foa fob bar baz) :fuzzy-match t) :buffer "*helm test*")
The candidates list may be replaced by a function that produces a list. See (helm wiki) for details.
Helm's built-in fuzzy matcher is activated for some commands. Helm's fuzzy matching is disabled by default. Currently these commands support fuzzy matching:
helm-find-files: fuzzy matching enabled by default.
To globally enable fuzzy matching for
IMPORTANT: For faster fuzzy matching, set
helm-candidate-number-limit to 100 or less. Default is 100.
To re-size the completion window based on number of candidates:
Adjust minimum and maximum height of completion window using:
40 is the default value of
helm-autoresize-max-height, which sets the completion window height to 40% of the fame height.
helm-autoresize-min-height specifies the minimum height that the completion window cannot shrink to.
For a fixed window size, set
helm-autoresize-min-height equal to
These are popular applications developed using helm completion and narrowing framework. They are available for individual installs through the Emacs package manager. This list is not exhaustive.
helm-mode: turns on helm completions for most standard emacs completions. Helm provides even more optimized helm completions for some commands in helm-mode. Prefer these natively optimized versions over the ones in helm-mode.
helm-find-files: one command that handles all the files related commands (bind to
helm-buffers-list: provides enhanced buffers listing.
helm-browse-project: handles project files and buffers; defaults to current directory; works with
helm-find-files; recommended with helm-ls-git, helm-ls-hg and
helm-ls-svnfor a better handling of version control files.
helm-dabbrev: enhanced dabbrev implementation with helm completion; does not use emacs code.
helm-moccur: enhanced occur for one or more buffers; launch from
helm-imenu-in-all-buffers: provide imenus for current or all buffers.
helm-etags-select: enhanced etags with helm-completion; usable everywhere with
helm-apropos: enhanced apropos for functions and variables that
Grep: launch from any helm file commands; supports back-ends
agand custom implementation of
helm-gid: Helm interface for
helm-show-kill-ring: A helm browser for kill ring.
helm-all-mark-rings: A helm browser for mark ring; retrieves last positions in buffers.
helm-filtered-bookmarks: enhanced browser for bookmarks.
helm-list-elisp-packages: enhanced browser for elisp package management.
Recommended Helm extensions
Warning Helm development has sparked quite a few extensions, many
of which duplicate features already included in helm. Some of these
packages (about 20 at last count in the MELPA repository) are either
deprecated or unmaintained. Moreover, many remain out-of-sync with
helm core development cycles causing incompatibilities. To avoid
helm problems or unstable emacs, please look for comparable features
within helm and
emacs-helm before installing such
The Helm project has a currant unresolved issue list. Please feel free to fix any of them; send a pull request.
The Helm project maintains a list of contributors.
Bugs & Improvements
The Helm Team welcomes bug reports and suggestions. Note that not all bugs when using Helm are due to Helm. Because of the way Helm interacts with many Emacs features, bugs may be related to Emacs itself.
One way to ascertain that the bugs are helm-related, recreate the
error either by using
Emacs -Q or by running the included package
./emacs-helm.sh located in the helm directory.
The Helm Team