GNU Hyperbole:
The Everyday Hypertextual Information Manager
by Bob Weiner

Say thanks if you like Hyperbole.

Table of Contents

Hyperbole screenshot of the Koutliner, DEMO file and HyRolo


GNU Hyperbole has been greatly expanded (see HY-NEWS) and is compatible with Emacs 24.4 through Emacs 27 (typically any latest release).

Hyperbole is now available for download and installation via the GNU Emacs package manager or manually via ftp or git.

Hyperbole is designed and maintained by Bob Weiner and Mats Lidell.


GNU Hyperbole (pronounced Ga-new Hi-per-bo-lee) is an efficient and programmable hypertextual information management system implemented as a GNU Emacs package. It is a toolkit and user interface for viewing, retrieving and interlinking all kinds of textual information, utilizing Emacs for editing most of that information. Thus, you can build new classes of applications with it, but most people use it to speed their day-to-day information management and retrieval needs.

Hyperbole is like Markdown for hypertext. Hyperbole automatically recognizes dozens of common patterns in any buffer regardless of mode and can instantly activate them as hyperbuttons with a single key: email addresses, URLs, grep -n outputs, programming backtraces, sequences of Emacs keys, programming identifiers, Texinfo and Info cross-references, Org links, Markdown links and on and on. All you do is load Hyperbole and then your text comes to life with no extra effort or complex formatting.

If any term in here is new or unfamiliar to you, you can look it up in the Hyperbole Glossary.

Hyperbole lets you (see also Use Cases):

  1. Create your own button types and use buttons of those types to launch arbitrary actions. One action type is a link to a file;

  2. Build outlines with multi-level numbered outline nodes, e.g., that all renumber automatically as any node or tree is moved in the outline. Each node also has a permanent hyperlink anchor that you can reference from any other node;

  3. Manage all your contacts quickly with hierarchical categories and embed hyperlinks within each entry. Or create an archive of documents with hierarchical entries and use the same search mechanism to quickly find any matching entry;

  4. Use single keys to easily manage your Emacs windows or frames and quickly retrieve saved window and frame configurations;

  5. Search for things in your current buffers, in a directory tree or across major web search engines with the touch of a few keys.

The common thread in all these features is making retrieval, management and display of information fast and easy. That is Hyperbole's purpose. It may be broad but it works amazingly well. If it is textual information, Hyperbole can work with it.

Hyperbole allows hypertext buttons to be embedded within unstructured and structured files, mail messages and news articles. It offers intuitive keyboard and mouse-based control of information display within multiple windows. It also provides point-and-click access to World-Wide Web URLs, Info manuals, ftp archives, etc.

Hyperbole includes easy-to-use, powerful hypertextual button types that work without the need for a markup language. Hyperbole's button types are written in Lisp and can be wholly independent of the web, i.e. web links are one type of Hyperbole link, not fundamental to its link architecture. However, Hyperbole is a great assistant when editing HTML or Javascript or when browsing web pages and links.

In contrast to Org mode, Hyperbole features work across all Emacs modes. Hyperbole speeds your work by turning all kinds of textual references into clickable hyperlinks and allowing you to create new hyperlinks by dragging between two windows. The Hyperbole wiki page explains the many ways it differs from and is complementary to Org mode. Hyperbole and Org mode are compatible and may be used together.

Hyperbole is something to be experienced and interacted with, not understood from reading alone. If you value learning fewer packages and getting more work done faster, then Hyperbole is for you.

Hyperbole works well on GNU Emacs 24.4 or above. Its main distribution site is:

Hyperbole is available for download and installation through the GNU Emacs package manager, ELPA.

Mailing Lists
User list for GNU Hyperbole (info and subscription, web archive).
List for bug reporting (info and subscription, web archive).

Ftp and Git Source Code-only Downloads

To inspect the Hyperbole source code online rather than installing it for use (which will also give you the source code), open a web page to:

Alternatively, you may download a tar.gz source archive from either:


which will find the closest mirror of the GNU ftp site and show it to you.

If you want to follow along with Hyperbole development and maintain a copy/clone of the current version-controlled git tree, use the command listed here to clone the Hyperbole project tree.


Once you have Emacs set up at your site, GNU Hyperbole may be installed by using the Emacs Package Manager. If you are not familiar with it, see the Packages section of the GNU Emacs Manual, Emacs Packages.

If you have Hyperbole 5.10 or higher already installed and simply want to upgrade it, invoke the Emacs Package Manager with {M-x list-packages RET}, then use the {U} key followed by the {x} key to upgrade all out-of-date packages, Hyperbole among them. Then skip the text below and move on to the next section, Invocation and Documentation.

Otherwise, to download and install the Hyperbole package, you should add several lines to your personal Emacs initialization file, typically "~/.emacs". For further details, see Emacs Init File.

Below are the lines to add:

(require 'package)
      (setq package-enable-at-startup nil) ;; Prevent double loading of libraries
      (unless (package-installed-p 'hyperbole)
        (package-install 'hyperbole))
      (require 'hyperbole)

Now save the file and then restart Emacs. Hyperbole will then be downloaded and compiled for use with your version of Emacs; give it a minute or two. You may see a bunch of compilation warnings but these can be safely ignored.

Invocation and Documentation

Once Hyperbole has been installed for use at your site and loaded into your Emacs session, it is ready for use. You will see a Hyperbole menu on your menubar and {C-h h} will display a Hyperbole menu in the minibuffer for quick keyboard-based selection. For example, {C-h h d w} displays a Hyperbole auto-numbered outline documenting why one might use Hyperbole (use cases).

You can invoke Hyperbole commands in one of three ways:

1. use the Hyperbole menu on your menubar;

Hyperbole Menubar Menu

2. type {C-h h} or {M-x hyperbole RET} to bring up the Hyperbole main menu in the minibuffer window, for fast keyboard or mouse-based selection; select an item from this menu by typing the item's first letter; use {q} to quit from the menu.

3. use a specific Hyperbole command such as an Action Key click {M-RET} on a pathname to display the associated file or directory.

Use {C-h h d d} for an interactive demonstration of standard Hyperbole capabilities, including the HyRolo contact manager.

Hyperbole screenshot of the DEMO

{C-h h k e} offers a interactive example of Koutliner usage, Hyperbole's multi-level, autonumbered, hypertextual outliner.

Hyperbole screenshot of the Koutliner

To try out HyControl, Hyperbole's interactive frame and window control system, use {C-h h s w} for window control or {C-h h s f} for frame control. {t} switches between window and frame control once in one of them. Hyperbole also binds {C-c \} for quick access to HyControl's window control menu if it was not already bound prior to Hyperbole's initialization. Here is a long video demonstrating most of HyControl's features.

The above are the best interactive ways to learn about Hyperbole.

But Hyperbole also includes the Hyperbole Manual, a full reference manual, not a simple introduction. It is included in the "man/" subdirectory of the Hyperbole package directory in four forms: - online Info browser version
hyperbole.html - web HTML version
hyperbole.pdf - printable version
hyperbole.texi - source form

The Hyperbole package installation places the Info version of this manual where needed and adds an entry for Hyperbole into the Info directory under the Emacs category. {C-h h d i} will let you browse the manual. For web browsing, point your browser at "${hyperb:dir}/man/hyperbole.html", wherever the Hyperbole package directory is on your system; often this is: "~/.emacs.d/elpa/hyperbole-${hyperb:version}/".

Hyperbole Components

Hyperbole consists of five parts:

  1. Buttons and Smart Keys: A set of hyperbutton types which supply core hypertext and other behaviors. Buttons may be added to documents (explicit buttons) with a simple drag between windows, no markup language needed. Implicit buttons are patterns of regular text that Hyperbole recognizes and then uses to perform specified actions, e.g. bug#24568 displays the bug status information for that bug number.

    These actions may be links or arbitrary Lisp expressions. So for example, you could create your own button type of Wikipedia searches that jumped to the named Wikipedia page whenever point was within text of the form [wp]. You define the pattern so {} might do the same thing if you preferred. And this works within any Emacs buffer you want it to, regardless of major or minor mode.

    Buttons are accessed by clicking on them or referenced by name (global buttons), so they can be activated regardless of what is on screen. Users can make simple changes to button types and those familiar with Emacs Lisp can prototype and deliver new types quickly with just a few lines of code.

    Hyperbole includes two special `Smart Keys', the Action Key and the Assist Key, that perform an extensive array of context-sensitive operations across emacs usage, including activating and showing help for Hyperbole buttons. In many popular Emacs modes, they allow you to perform common, sometimes complex operations without having to use a different key for each operation. Just press a Smart Key and the right thing happens;

  2. Contact and Text Finder: an interactive textual information management interface, including fast, flexible file and text finding commands. A powerful, hierarchical contact manager, HyRolo, which anyone can use is also included. It is easy to learn to use since it introduces only a few new mechanisms and has a menu interface, which may be operated from the keyboard or the mouse.

    HyRolo Menubar Menu

  3. Screen Control: Hyperbole includes HyControl, the fastest, easiest-to-use window and frame control, available for GNU Emacs. With just a few keystrokes, you can shift from increasing a window's height by 5 lines to moving a frame by 220 pixels or immediately moving it to a screen corner. Text in each window or frame may be enlarged or shrunk (zoomed) for easy viewing, plus many other features.

    The broader vision for HyControl is to support persistent window and frame configurations as link targets. Then a user will be able to create the views of information he wants and store them as links for rapid display. Work remains to implement this feature but it helps explain the connection of HyControl to the rest of Hyperbole;

  4. The Koutliner: an advanced outliner with multi-level autonumbering and permanent ids attached to each outline node for use as hypertext link anchors, per node properties and flexible view specifications that can be embedded within links or used interactively;

  5. Programming Library: a set of programming library classes for system developers who want to integrate Hyperbole with another user interface or as a back-end to a distinct system. (All of Hyperbole is written in Emacs Lisp for ease of modification. Hyperbole has been engineered for real-world usage and is well structured).

We find Hyperbole's parts are more powerful as one package, i.e. the sum is greater than the parts, so we don't offer them separately. Hyperbole is free software, however, so you may modify it as you see fit.

Hyperbole Buttons

A Hyperbole hypertext user works with buttons; he may create, modify, move or delete buttons. Each button performs a specific action, such as linking to a file or executing a shell command.

There are three categories of Hyperbole buttons:

  1. Explicit Buttons created by Hyperbole, accessible from within a single document;

  2. Global Buttons created by Hyperbole, accessible anywhere within a user's network of documents;

  3. Implicit Buttons buttons created and managed by other programs or embedded within the structure of a document, accessible from within a single document. Hyperbole recognizes implicit buttons by contextual patterns given in their type specifications.

Hyperbole buttons may be clicked upon with a mouse to activate them or to describe their actions. Thus, a user can always check how a button will act before activating it. Buttons may also be activated from a keyboard. (In fact, virtually all Hyperbole operations, including menu usage, may be performed from any standard terminal interface, so one can use it on distant machines that provide limited display access).

Hyperbole does not enforce any particular hypertext or information management model, but instead allows you to organize your information in large or small chunks as you see fit, organizing each bit as time allows. The Hyperbole Koutliner and HyRolo tools organize textual hierarchies and may also contain links to external information sources.

Important Features

Some of Hyperbole's most important features include:

Hyperbole Uses

Typical Hyperbole uses include:

User Quotes

*** MAN I love Hyperbole!!! Wow! ***

                    -- Ken Olstad  
                       Cheyenne Software, Inc.

I love koutlines.

                    -- Bob Glickstein  
                       Z-Code Software Corporation

One of the nicest things about Hyperbole is that it's available everywhere. Org-mode is a mode and its features are only available in Org files. For instance if you dropped into `eshell' or `ansi-term' and did `ls', you can move point to any of the directory's contents, do M-RET (or Shift-Button2) and jump to that file. And that's just one example. Note that this means that all Hyperbole functionality is available in Org files as well. To me, except for the Hyperbole outliner, that means complementary not conflicting. It's Hyperbole *and* org-mode, not Hyperbole vs. org-mode.

Additionally, off the bat, I found it very well documented and for me that's a proxy for the quality of a package. The maintainers are quite responsive. There's plenty more functionality that I haven't uncovered yet but due to the ease of installation and the quality of the documentation, digging into it is actually fun.

                    -- Aditya Siram  

For me, Emacs isn't Emacs without Hyperbole. I have depended on Hyperbole daily since 1992, when I first started using it to manage my development environment. It didn't take long before I could summon almost any information I needed directly from within my editing environment with an implicit button. Since I almost never have to slow down to look for things--one context-dependent button usually produces exactly what I need --I am able to maintain focus on the task I am working on and complete it more quickly. With its gestural interface, seamless integration with other Emacs packages and incredibly useful set of core features. I think that Hyperbole is one of the best designed and most easily extensible software products I have ever come across. It is certainly the one which has made the biggest improvement in my personal productivity.

My Hyperbole button file is my start page in Emacs. It's a quickly searchable index with links to countless resources. We also have a library of implicit buttons that enable rapid navigation from references in our code to our issue tracking system, so clicking a reference like Client6502 opens the relevant conversation. Hyperbole provides a really useful set of power tools. If Emacs is your preferred productivity environment, it's definitely worth getting familiar with it.

                    -- Chris Nuzum  
                       Co-founder, Traction Software, Inc.

I've found Hyperbole (in conjunction with XEmacs) to be very useful for signal processing algorithm development.

For me, it has almost completely obsoleted the engineering notebook: I keep a set of files with ideas, algorithms, and results, linked together and to the implementation in C++ files. Using XEmacs' support for embedding graphics, I've written a mode that accepts image tags (formatted like HTML), and reads in GIF files to display plots. I have another program that converts the file to HTML (not perfect, but adequate), so I can put any aspect of development on our internal web for others to see.

                    -- Farzin Guilak  
                       Protocol Systems, Inc., Engineer

I am blind and have been using Hyperbole since 1992. I used to use a PC as a talking terminal attached to a UNIX system, but then I developed Emacspeak which lets me use Emacs and Hyperbole from standard UNIX workstations with an attached voice synthesizer.

My main uses are:

  1. Global and implicit buttons for jumping to ftp sites.

  2. The contact manager with Emacspeak support.

  3. Explicit buttons as part of comments made about a structured document. Each button jumps to the document section referred to by the comment. This is very, very useful.

  4. The Hyperbole Koutliner, which I find a very useful tool. I've implemented Emacspeak extensions to support it.

                    -- TV Raman  
                       Google Inc.

I've been a grateful Hyperbole user for a few years now. Hyperbole's flexibility and ease of use is a marvel.

Mainly, I write easy little implicit button types (and corresponding action types) to make my life easier. For example, I have an implicit button type to bury certain buffers when I click at their bottoms, one that recognizes a bug report record in various contexts and edits it, one that links pieces of test output in a log file to the corresponding test case source code (EXTREMELY helpful in interpreting test output), others that support our homegrown test framework, one that handles tree dired mode the way I'd like, one that completely handles wico menus (I've also overloaded the wconfig actions triggered by diagonal mouse drags with wicos actions), and a couple that support interaction with BBDB.

Other than that, I keep a global button file with 30 or so explicit buttons that do various little things, and I index saved mail messages by putting explicit link-to-mail buttons in an outline file.

                    -- Ken Olstad  
                       Cheyenne Software, Inc.

In general, Hyperbole is an embeddable, highly extensible hypertext tool. As such, I find it very useful. As it stands now, Hyperbole is particularly helpful for organizing ill-structured or loosely coupled information, in part because there are few tools geared for this purpose. Hyperbole also possesses a lot of potential in supporting a wider spectrum of structuredness, ranging from unstructured to highly structured environments, as well as structural changes over time.

Major Uses:

Hyperbole is the first hyper-link system I've run across that is actually part of the environment I use regularly, namely Emacs. The complete flexibility of the links is both impressive and expected -- the idea of making the link itself programmable is clever, and given that one assumes the full power of Emacs. Being able to send email with buttons in it is a very powerful capability. Using ange-ftp mode, one can make file references "across the world" as easily as normal file references.

                    -- Mark Eichin  
                       Cygnus Support

I just wanted to say how much I enjoy using the Hyperbole Koutliner. It is a great way to quickly construct very readable technical documents that I can pass around to others. Thanks for the great work.

                    -- Jeff Fried  

The Hyperbole system provides a nice interface to exploring corners of Unix that I didn't know existed before.

                    -- Craig Smith  

Why was Hyperbole developed?

Hyperbole was originally designed to aid in research aimed at Personalized Information production/retrieval Environments (PIEs). Hyperbole was a PIE Manager that provided services to PIE Tools. PIEmail, a mail reader was the only PIE Tool developed as part of this research but Hyperbole has greatly expanded since then and has long been a production quality toolset.

An examination of many hypertext environments as background research did not turn up any that seemed suitable for the research envisioned, mainly due to the lack of rich, portable programmer and user environments. We also tired of trying to manage our own distributed information pools with standard UNIX tools. And so Hyperbole was conceived and raved about until it got its name.

Since then Hyperbole has proved indispensible at improving information access and organization in daily use over many years. Why not start improving your information handling efficiency today?

Registration Date: Thu 07 Aug 2003 07:52:35 AM CEST
License: GNU General Public License v3 or later
Development Status: 6 - Mature

Return to GNU's home page.

Please send FSF & GNU inquiries & questions to There are also other ways to contact the FSF.

Please send comments on these web pages to, send other questions to

Copyright (C) 1998-2016 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Last modified: 2016-08-10T17:32:51UTC