Quick Start

Install W3M from any package manager of your respective Linux or Unix-based distribution. Being such an old and ubiquitous utility, I can't think of any mainstream distribution that wouldn't offer it.

Download my keymap. While you can remap anything to your liking, throughout this site I assume you follow my mappings. Some coincide with the defaults, some modify them, while some merely expand (as W3M allows multiple mappings to the same operation):

$ cd ~/.w3m
$ wget https://raw.githubusercontent.com/vparnas/config/master/.w3m/keymap

Start W3M in one of these manners:

$ w3m -v # built-in page
$ w3m -B # bookmark page
$ w3m URL
$ w3m URL URL2 URL3
$ w3m -N URL URL2 URL3  # load each url in a separate tab
$ w3m local file

# Configure home page if w3m started with no arguments
$ export WWW_HOME=URL
$ w3m


The keymap enables many vi-compatible strokes, though with deviations, and in general strives for one-stroke convenience and multiple variations.

Importantly, SPACE, +, =, CTRL-D, DOWN, PAGEDOWN all proceed to the next page. Likewise, -, CTRL-U, UP, PAGEUP proceed to the previous page.

* I specifically enabled the variety of one-stroke page-by-page shortcuts (including the counter-intuitive DOWN/UP keys for this purpose) to allow easy, E-Book reader-like ease of navigation.

TAB and SHIFT+TAB navigate across links and forms.

[ , ] respectively jump to the first and last links.

g, G (in addition to HOME and END) jump to the page top and bottom.


Though with notable limitations (below), I find the mark system highly convenient for effective browsing and reading.

I've modified the keystrokes from the default to these much more convenient one-stroke variants:

m to set/unset a mark, whose cursor position W3M highlights in yellow by default.

. , (period and comma) to navigate across the existing marks within the page. Rarely (actually, in no other browser) do I recall this seamless and cyclical means of mark usage.

See the config section for more related keystrokes.

As for the limitations, first, the marks remain only for the lifetime of the buffer and the W3M session.

Second, the marks disappear if you resize or reset your terminal, or change the terminal font. So avoid that ... if you wish to retain those marks.


The standard, vi-compatible search keys are / ?. Having initiated the search, use n, N to cycle back and forth.

Additionally, W3M offers the incremental search. Hit CTRL-S, start typing a search pattern, and the page will instantly transition to the next matching location. Hit CTRL-S again to repeatedly proceed further through the (so-far) matchings. CTRL-R works analogously, but backwards.

The incremental search is a handy way to explore the search space without abandoning your current position until you hit ENTER to land at the currently highlighted result.

Buffers vs tabs


Ultimately, W3M caches all loaded URLs or local files in buffers. The urls you open via the command line or in the course of navigating, will, by default stack buffers, one on top of another.

Referring to the keymap, you may navigate back and forth through these buffers via <, LEFT, >, RIGHT keys.

As you do, the loaded buffers stay in memory, and their access is instantaneous (contrary to the back/forth operations of a graphical browser, which may need to reload graphical and/or certain network elements, even if the page is technically cached.)

To return to the previous buffer and close (unload) the current (this more inline with a traditional browser), press B.

s displays the buffer selection menu. There you may also choose among the loaded buffers, or delete/unload with D.


W3M also supports tabs, each tab abstracting it's own set of buffers. (I've long since used tabs, not in W3M, not in any application that supports the buffer mode of operation, as a tab bar not only takes up extra screen real estate, but also tends to distract.)

However, for you tabbers out there, the tab navigation keys perform the expected behavior.

Briefly, CTRL-t, CTRL-w open/close a tab, { } cycle among them, ALT-t opens a tab menu similar to the buffer menu.

In addition, $ w3m -N URL1 URL2 URL3 on the command line opens all indicated urls in separate tabs.

Opening URLs, links

U: open a new URL via a dialog.
R: reload the page
Enter: follow the selected link.
t T: follow link in a new tab.
I: When on an image placeholder, download and open the image externally (typically via xdg-open, which knows how to handle the image).

External programs

Configure up to nine external programs for handling URLS via the following keystrokes:

O: open current page in an external program.
o (lowercase): open the highlighted link externally.

The above open the page/link via the app in the extbrowser config option, which opens the url with the default, (usually) graphical browser.

As far as extbrowser2, 3, ..., 9, precede the O/o shortcuts with the appropriate index. In my config, 7o copies the hovered url to a tmux buffer (if using tmux). Or 8O would copy the current URL to the X clipboard.

This external program feature is extremely powerful, as it allows you to interface the url with any graphical or CLI app or pipe.

Saving, downloading

Alt-s: Save the source (html) to disk.
S: Save the rendered buffer (effectively what you see) to disk.
a: Download the source of the highlighted link.
Alt-I: Download the highlighted image.

Viewing the source and buffer editing

v: view document source. The source opens as any other buffer which you may appropriately handle and manipulate.
E: edit the document source in your external document editor. See the editor variable in the config.

Buffer editing

One of the more powerful features:

Alt-e: edit the rendered buffer in the external editor.

Forms, input

Hover over an editable field and press Enter to enter the input line editing mode (the same mode as when entering a new url) to enter/modify the desired text.

Alternatively, you may edit the input line via your configured editor with CTRL-o.

To trigger the submit action (the SUBMIT internal command), either press Enter over the respective submit button, or CTRL-c over any field belonging to that form.

Custom commands and macros

The internal COMMAND directive enables you to combine multiple commands. Easiest is to demonstrate by example. See the handful of macros I've defined.

If you often visit a noisy (cluttered) page, for instance, you could devise a macro to either directly land you at the desired location (via a search, a fixed number of links or fields through the page or, a specific line number, if desperate), or involving the pipe (PIPE_BUF) command, to entirely strip the page to your desired content (via the Unix grep or similar).

Other features

Alt-a opens the Add Bookmark dialog.
Alt-b opens the bookmark list, split into different categories accessible to the dialog above.
Alt-r reloads the configuration and keymap if edited during the session.
CTRL-h opens the url history.

Here I've exhibited only the most ubiquitous features you may initially need. Explore a lot more in the keymap, the W3M help dialog (press H), the config options, the man page, the command line help ($ w3m -h) for more information and ideas.

Use as an E-Reader