Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Official user guide
This guide will teach you how to efficiently use
The main window consists of three panels by default (it's called Miller columns by the way):
- the middle one with the contents of the current directory,
- the left one shows the parent directory, with the current directory highlighted,
- the right one serves various previews; I will tell you more about it later.
If you're familiar with vim, you should feel right at home with
ranger's UI conventions.
ranger uses the "hjkl" keys for navigation
and borrows many idioms from
vim. For example: "yy" (copy line in
vim) copies a file, "pp" pastes it and "dd" cuts the file. The more
complex functions may be called from the command line invoked with ":"
The current file's attributes may be seen at the bottom and the current directory path may be seen at the top.
If you're familiar with
mc (Midnight Commander) the first thing you
may notice is the lack of the second panel for the file navigation. It
may seem like a limitation but in most cases people use only one panel
at a time.
ranger allows you to create new tabs (like in a web
browser) and switch between them with either
you open just two tabs,
ranger's tabs effectively behave just like
mc's panels. And you can even open more if such need arises.
The basic movement keys are inspired by
vim: "jk" moves up and down,
"l" enters the selected directory or opens a file and "h" returns to the
parent directory. Many other navigation keys known from
vim work too,
feel free to try them.
ranger uses 4 main configuration files:
commands.pycontains various functions' implementation, written in Python, used to modify
rc.confis used for setting various options and binding the keys to functions,
rifle.confdecides which program to use for opening which file,
scope.shis a shell script used to generate the previews for various file types.
It's quite common to use
ranger --copy-config=all to copy the
default config files to
~/.config/ranger and modify them there. Be
aware that for
commands.py, ranger reads both the global and
the user's config (in that order). It allows the user to maintain only a small
config which sets only the things not set in the default one. For
rifle.conf, ranger reads either the users or the global config.
The best practice is to only add the options/keybindings you actually want to
change to your rc.conf, rather than to have a complete copy of the default
rc.conf. This eliminates the need to update your config manually and gives you
the benefits from new options/keybindings of future ranger versions.
If you want to keep the full rc.conf though, you may want to set the
FALSE to avoid loading
both the default and your own rc.conf. In this case you have to update your
config manually though.
To open a file and let Ranger choose which program to use to open it with (via
rifle), just press Enter. To choose yourself, press
r, and either choose
from the list or type the program you want to use. You can also use the command
To add a file handler to Ranger's repertoire, run the command
ranger --copy-config=rifle, then edit the resulting file. For example, to add
Kolourpaint as an image editor, you could add:
mime ^image, has kolourpaint, X, flag f = kolourpaint -- "$@"
The order of statements in this file reflects the order programs will be used
and appear on the
r list in.
To copy a file, highlight it, press "yy" to mark it for copying
(analogously to copying a line in
vim with "yy"), then navigate to a
target directory (or switch a tab if you decided to do it the "
way") and then press "pp" to paste it (again, almost like in
(To copy only the directory, filename, or file path with name as text to your clipboard — requires that xclip, xsel or pbcopy (in case of mac os) is installed — use "yd", "yn", and "yp" respectively. Copying actual files remains internal to ranger.)
Moving a file differs very little from copying it: just use "dd" instead of "yy" at the beginning.
To copy/move multiple files, just mark them with
Space then use
"dd/yy". If you want to operate on multiple files stored in different
directories, you may use "ya/da" to add them to the list of files to be
copied/moved before pasting them.
(Note that the copy/cut buffers can be used for other operations as
well, by using the "%c" macro in your commands. For example, adding
files to the cut/copy buffer using "ya"/"da" then using the
:shell -w printf %c | xargs rm command allows you to delete multiple files in
multiple directories. Remember to clear the buffer once you're done
If you'd like to copy files from one ranger instance to another, type
:save_copy_buffer in one and
:load_copy_buffer in the other ranger
instance. This method can also be used to export a list of files. They are
saved in the file
If you're working in more than one directory at a time -- and you most
likely do -- you may create tabs for each directory to which you want to
have a quick access. The tabs are numbered. To switch to the N-th tab,
N is the tab number. If such tab does not exist
yet, it will be created. To close a tab, press "q" (if you close the
last tab, the entire
ranger process will close).
I've mentioned the previews in the right column of
ranger. I believe
they deserve a separate section in this guide.
All file previews are supplied by the
scope.sh config file. It is a
regular shell script and it's behavior is documented in detail inside of
A very special case of the previews are the image previews. Yes,
ranger can display images in your terminal. It uses an utility
supplied with the
w3m web browser (sometimes packaged in a separate
w3m-img in Debian). While it's reliable most of the
time, please be aware that it is a hack and may behave very strangely at
Since the commit
9b73aeb (merged around 10 October 2016)
ranger supports reliable image previews in
iTerm2 terminal emulators. To enable it, set
preview_images_method to either
iTerm2. Please refer to the documentation for further information. For the
urxvt method to work on Arch Linux it might be needed to install the
rxvt-unicode-pixbuf package instead of the regular
Custom image previews
In the recent versions of
ranger, the mechanism of the image previews
was extended and generalized. When calling
ranger sets the
$cached environmental variable containing a unique path to a file
where the image preview may be generated if needed.
scope.sh may then
save an image to that path and exit with the exitcode "6" (documented
scope.sh, may be a subject to some changes) to tell
use it. Simply saying: if you can convert a file to a jpg,
able to show a graphical preview for it. Videos, PDFs, all sort of
rifle is a powerful smart file opener bundled with
tries to guess with what program it should open a given file based on
its MIME type, extension, the available programs and a few other
factors. It is configured with the
rifle.conf file. It is used by
ranger internally but may be used as a standalone program too.
By pressing "t" you may mark a file with an asterisk ("*"). It is persistent and will be there until you remove it manually. It may be used for example for marking the already read e-books, or files that need some action.
You can actually mark files with almost any other character besides the asterisk. Pressing a quotation mark (' " ') followed by any other character marks the file with that character.
The tags may also be used to automatically enable some options in
certain directories. Refer to the documentation of the
Storing the file metadata is a brand new feature of
ranger. It may
be used to add arbitrary key-value data to any file. Calling
:meta title a very interesting title will set the tag "title" of the
current file to "a very interesting title".
:meta is most commonly used in conjunction with
built-in linemodes are bound to "M" followed by some letter. At the
moment of writing this guide, there are 6 built-in linemodes:
filename: no metadata, the default mode of ranger,
permissions: file permissions are displayed next to the files,
fileinfo: show file type information based on shell
mtime: show the modified time of files
sizemtime: show the size and the modified time
metatitle: see below.
The last line mode,
metatitle, is extremely handy for organizing all
sorts of documents: books, movies, pictures and more. It displays the
files based on their metadata. The current format is:
[[year - ]title] alignment [authors]. Bracketed content is ignored
if empty. The
title field is mandatory for this to work. To define
a custom linemode, please refer to this page:
:meta stores the metadata in the ".metadata.json" file for each
directory in which it is used.
If you're browsing a moderetely nested directory tree, you may find
:flat useful. It allows to browse a directory tree in a linear
fashion: all the files up to the n-th level are shown together. It's a
bit hard to explain so just call
:flat 1 and observe what happens.
The argument is the maximum number of directories to flatten. Pass -1
for no limit (use with caution!) and 0 to disable
ranger supports bulk file renaming with the
Mark the files that you want to rename and call
should open a file containing a list of these files in your text
editor (determined with
rifle). You may freely change the names in
that file. When you are done, save the file and close the editor.
ranger will show you a preview of what will happen in a few moments.
:bulkrename works great with