| RANGER(1) | ranger manual | RANGER(1) |
ranger [--version] [--help] [--debug] [--clean] [--cachedir=directory] [--confdir=directory] [--datadir=directory] [--copy-config=which] [--choosefile=target] [--choosefiles=target] [--choosedir=target] [--selectfile=filepath] [--show-only-dirs] [--list-unused-keys] [--list-tagged-files=tag] [--profile] [--cmd=command] [path ...]
ranger is a console file manager with VI key bindings.
This manual contains instructions on how to use and configure ranger.
Inside ranger, you can press ? for a list of key bindings, commands or settings.
The file README.md contains install instructions.
The file HACKING.md contains guidelines for code modification.
The directory doc/configs contains configuration files. They are usually installed to /etc/ranger/config and can be obtained with ranger's --copy-config option.
The directory examples contains reference implementations for ranger plugins, sample configuration files and some programs for integrating ranger with other software. They are usually installed to /usr/share/doc/ranger/examples.
The man page of rifle(1) describes the functions of the file opener
The section LINKS of this man page contains further resources.
Note: You may want to disable loading of the global configuration files by exporting RANGER_LOAD_DEFAULT_RC=FALSE in your environment. See also: FILES, ENVIRONMENT
--copy-config=commands will copy only a small sample configuration file with a thoroughly commented example. It is recommended to keep this file tidy to avoid getting defunct commands on ranger upgrades. The full default commands.py can be copied with --copy-config=commands_full, but that file will be ignored by ranger and serves only as a reference for making your own commands.
This part explains how certain parts of ranger work and how they can be used efficiently.
Tags are single characters which are displayed left of a filename. You can use tags however you want. Press "t" to toggle tags and "ut" to remove any tags of the selection. The default tag is an Asterisk ("*"), but you can use any tag by typing "<tagname>.
By default, only text files are previewed, but you can enable external preview scripts by setting the option "use_preview_script" and "preview_files" to true.
This default script is %rangerdir/data/scope.sh. It contains more documentation and calls to many external programs to generate previews. They are automatically used when available but completely optional.
Install these programs (just the ones you need) and scope.sh will automatically use them.
Independently of the preview script, there is a feature to preview images by drawing them directly into the terminal. To enable this feature, set the option "preview_images" to true and enable one of the image preview modes:
iTerm2
This only works in iTerm2 compiled with image preview support, but works over ssh.
To enable this feature, set the option "preview_images_method" to iterm2.
This feature relies on the dimensions of the terminal's font. By default, a width of 8 and height of 11 are used. To use other values, set the options "iterm2_font_width" and "iterm2_font_height" to the desired values.
kitty
This only works in Kitty. It requires PIL (or pillow) to work. Allows remote image previews, for example in an ssh session.
To enable this feature, set the option "preview_images_method" to kitty.
terminology
This only works in terminology. It can render vector graphics, but works only locally.
To enable this feature, set the option "preview_images_method" to terminology.
ueberzug
Ueberzug is a command line utility which draws images on terminals using child windows. It requires PIL (or pillow) and relies on X11. This makes it compatible (in a limited way, i.e., tmux splits are not supported) with many terminals and tmux but not the Linux console or Wayland.
To enable this feature, set the option "preview_images_method" to ueberzug.
urxvt
This only works in urxvt compiled with pixbuf support. Does not work over ssh.
Essentially this mode sets an image as a terminal background temporarily, so it will break any previously set image background.
To enable this feature, set the option "preview_images_method" to urxvt.
urxvt-full
The same as urxvt but utilizing not only the preview pane but the whole terminal window.
To enable this feature, set the option "preview_images_method" to urxvt-full.
w3m
This does not work over ssh, requires certain terminals (tested on "xterm" and "urxvt") and is incompatible with tmux, although it works with screen.
To enable this feature, install the program "w3m" and set the option "preview_images_method" to w3m.
When using a terminal with a nonzero border which is not automatically detected, the w3m preview will be misaligned. Use the "w3m_offset" option to manually adjust the image offset. This should be the same value as the terminal's border value.
The selection is defined as "All marked files IF THERE ARE ANY, otherwise the current file." Be aware of this when using the :delete command, which deletes all files in the selection.
You can mark files by pressing <Space>, v, etc. A yellow Mrk symbol at the bottom right indicates that there are marked files in this directory.
Macros can be used in commands to abbreviate things.
%f the highlighted file %d the path of the current directory %s the selected files in the current directory %t all tagged files in the current directory %c the full paths of the currently copied/cut files %p the full paths of selected files
The macros %f, %d, %p, and %s also have upper case variants, %F, %D, %P, and %S, which refer to the next tab. To refer to specific tabs, add a number in between. (%7s = selection of the seventh tab.)
%c is the only macro which ranges out of the current directory. So you may "abuse" the copying function for other purposes, like diffing two files which are in different directories:
Yank the file A (type yy), move to the file B, then type @diff %c %f
Macros for file paths are generally shell-escaped so they can be used in the "shell" command.
When mapping keys you can use the placeholder <any>, the key entered in that position can be used through the %any and %any_path macros. (When using multiple <any> placeholders you can index the macros: %any0, %any_path0, %any1, %any_path1...) The macro %any will be replaced with the key pressed in the position of the <any> placeholder. The macro %any_path will be replaced with the path of the bookmark mapped to the key pressed in the position of the <any> placeholder. For example this macro can be used to echo the key that was pressed after "c":
map c<any> echo %any
%any is used in the ranger configuration to create a keybinding for adding a bookmark. c<set_bookmark> creates a bookmark for the current directory and the key for the bookmark is the first supplied argument. In this case the key pressed after "m":
map m<any> set_bookmark %any
The %any_path macro can be used to echo the path of the bookmark that is set to the key pressed after "c":
map c<any> echo %any_path
A practical example of the use of %any_path is the pasting of cut/copied files to a bookmarked directory:
map p'<any> paste dest=%any_path
The macro %rangerdir expands to the
directory of ranger's python library, you can use it for something like this
command:
alias show_commands shell less
%rangerdir/config/commands.py
%confdir expands to the directory given by --confdir.
%datadir expands to the directory given by --datadir.
The macro %space expands to a space character. You can use it to add spaces to the end of a command when needed, while preventing editors to strip spaces off the end of the line automatically.
To write a literal %, you need to escape it by writing %%.
Note that macros are expanded twice when using chain. For example,
to insert a space character in a chained command, you would write %%space:
chain command1; command2%%space
Type m<key> to bookmark the current directory. You can re-enter this directory by typing `<key>. <key> can be any letter or digit. Unlike vim, both lowercase and uppercase bookmarks are persistent.
Each time you jump to a bookmark, the special bookmark at key ` will be set to the last directory. So typing "``" gets you back to where you were before.
Bookmarks are selectable when tabbing in the :cd command.
Note: The bookmarks ' (Apostrophe) and ` (Backtick) are the same.
Rifle is the file opener of ranger. It can be used as a standalone program or a python module. It is located at $repo/ranger/ext/rifle.py. In contrast to other, more simple file openers, rifle can automatically find installed programs so it can be used effectively out of the box on a variety of systems.
It's configured in rifle.conf through a list of conditions and commands. For each line the conditions are checked and if they are met, the respective command is taken into consideration. By default, simply the first matching rule is used. In ranger, you can list and choose rules by typing "r" or simply by typing "<rulenumber><enter>". If you use rifle standalone, you can list all rules with the "-l" option and pick a rule with "-p <number>".
The rules, along with further documentation, are contained in $repo/ranger/config/rifle.conf.
Flags give you a way to modify the behavior of the spawned process. They are used in the commands ":open_with" (key "r") and ":shell" (key "!").
f Fork the process, i.e. run in background. Please use this flag
instead of calling "disown" or "nohup", to avoid killing the
background command when pressing Ctrl+C in ranger.
c Run the current file only, instead of the selection
r Run application with root privilege (requires sudo)
t Run application in a new terminal window
There are some additional flags that can currently be used only in the "shell" command: (for example ":shell -w df")
p Redirect output to the pager s Silent mode. Output will be discarded. w Wait for an Enter-press when the process is done
By default, all the flags are off unless otherwise specified in rc.conf key bindings or rifle.conf rules. You can specify as many flags as you want. An uppercase flag negates the effect: "ffcccFsf" is equivalent to "cs".
The terminal program name for the "t" flag is taken from the environment variable $TERMCMD. If it doesn't exist, it tries to extract it from $TERM, uses "x-terminal-emulator" as a fallback, and then "xterm" if that fails.
Examples: ":open_with c" will open the file that you currently point at, even if you have selected other files. ":shell -w df" will run "df" and wait for you to press Enter before switching back to ranger.
ranger's plugin system consists of python files which are located in ~/.config/ranger/plugins/ and are imported in alphabetical order when starting ranger. A plugin changes rangers behavior by overwriting or extending a function that ranger uses. This allows you to change pretty much every part of ranger, but there is no guarantee that things will continue to work in future versions as the source code evolves.
Adding new commands via a plugin as simple as specifying them like you would do in the commands.py.
There are some hooks that are specifically made for the use in plugins. They are functions that start with hook_ and can be found throughout the code.
grep 'def hook_' -r /path/to/rangers/source
Also try:
pydoc ranger.api
Note that you should NOT simply overwrite a function unless you know what you're doing. Instead, save the existing function and call it from your new one. This way, multiple plugins can use the same hook. There are several sample plugins in the /usr/share/doc/ranger/examples/ directory, including a hello-world plugin that describes this procedure.
Key bindings are defined in the file %rangerdir/config/rc.conf. Check this file for a list of all key bindings. You can copy it to your local configuration directory with the --copy-config=rc option.
Many key bindings take an additional numeric argument. Type 5j to move down 5 lines, 2l to open a file in mode 2, 10<Space> to mark 10 files.
This list contains the most useful bindings:
Conflicts will be renamed by appending an '_' (and a counter if necessary), resulting in "file.ext_", "file.ext_0", etc. If you prefer "file_.ext" you can use the "paste_ext" command.
This section lists all built-in settings of ranger. The valid types for the value are in [brackets]. The hotkey to toggle the setting is in <brakets>, if a hotkey exists.
Settings can be changed in the file ~/.config/ranger/rc.conf or on the fly with the command :set option value. Examples:
set column_ratios 1,2,3 set show_hidden true
Toggling options can be done with:
set show_hidden!
The different types of settings and an example for each type:
setting type | example values ---------------+---------------------------- bool | true, false integer | 1, 23, 1337 string | foo, hello world list | 1,2,3,4 none | none
You can view a list of all settings and their current values by pressing "3?" in ranger.
sensitive
insensitive
smart
none no borders of any sort
outline draw an outline around all the columns
separators draw only vertical lines between columns
both both of the above
ranger --choosedir=/tmp/x --cmd='set global_inode_type_filter d'
set hidden_filter ^\.|~$
false turn the feature off
absolute absolute line numbers for use with "<N>gg"
relative relative line numbers for "<N>k" or "<N>j"
false start line numbers from 0
true start line numbers from 1
If there would be too many files for the system to handle, this option will be temporarily disabled automatically.
Note: You can reverse the order by typing an uppercase second letter in the key combination, e.g. "oN" to sort from Z to A.
disabled Don't display any information.
local Display only local state.
enabled Display both, local and remote state.
May be slow for hg and bzr.
You can enter the commands in the console which is opened by pressing ":".
You can always get a list of the currently existing commands by typing "?c" in ranger. For your convenience, this is a list of the "public" commands including their parameters, excluding descriptions:
alias [newcommand] [oldcommand] bulkrename cd [path] chain command1[; command2[; command3...]] chmod octal_number cmap key command console [-pSTARTPOSITION] command copycmap key newkey [newkey2...] copymap key newkey [newkey2...] copypmap key newkey [newkey2...] copytmap key newkey [newkey2...] cunmap keys... default_linemode [path=regexp | tag=tags] linemodename delete echo [text] edit [filename] eval [-q] python_code filter [string] filter_inode_type [dfl] find pattern flat level grep pattern help jump_non [-FLAGS...] linemode linemodename load_copy_buffer map key command mark pattern mark_tag [tags] meta key value mkdir dirname open_with [application] [flags] [mode] pmap key command prompt_metadata [key1 [key2 [...]]] punmap keys... quit quit! quitall quitall! relink newpath rename_append [-FLAGS...] rename newname save_copy_buffer scout [-FLAGS...] pattern search pattern search_inc pattern set option value setintag tags option value setlocal [path=<path>] option value shell [-FLAGS...] command source filename terminal tmap key command touch filename trash travel pattern tunmap keys... unmap keys... unmark pattern unmark_tag [tags]
There are additional commands which are directly translated to python functions, one for every method in the ranger.core.actions.Actions class. They are not documented here, since they are mostly for key bindings, not to be typed in by a user. Read the source if you are interested in them.
These are the public commands including their descriptions:
This shell script is opened in an editor for you to review. After you close it, it will be executed.
The octal number is between 000 and 777. The digits specify the permissions for the user, the group and others. A 1 permits execution, a 2 permits writing, a 4 permits reading. Add those numbers to combine them. So a 7 permits everything.
Key bindings in the form of [-+]<who><what> and <octal>= also exist. For example, +ar allows reading for everyone, -ow forbids others to write and 777= allows everything.
See also: man 1 chmod
To copy key bindings of the console, pager or taskview use "copycmap", "copypmap" or "copytmap" respectively.
Examples:
Set the global default linemode to "permissions":
:default_linemode permissions
Set the default linemode to "permissions" for all
files tagged with "p" or "P":
:default_linemode tag=pP permissions
Set the default linemode for all files in ~/books/ to
"metatitle":
:default_linemode path=/home/.*?/books/.* metatitle
Examples:
:eval fm
:eval len(fm.tabs)
:eval p("Hello World!")
This command is based on the scout command and supports all of its options.
:filter_stack add type f
:filter_stack add duplicate
:filter_stack add and
:filter_stack add type l
:filter_stack add or
Or using the mapped keys:
.f ." .& .l .|
Available subcommands:
This command is based on the scout command and supports all of its options.
Flags:
-r Jump in reverse order
-w Wrap around if reaching end of filelist
"filename": display each line as "<basename>...<size>" "fileinfo": display each line as "<basename>...<file(1) output>" "mtime": display each line as "<basename>...<mtime>" in ISO format "humanreadablemtime": display each line as "<basename>...<mtime>" in a human readable format, more precise the more recent. "sizemtime": display each line as "<basename>...<size> <mtime>" in ISO format "humanreadablesizemtime": display each line as "<basename>...<size> <mtime>" in a human readable format, more precise the more recent. "permissions": display each line as "<permissions> <owner> <group> <basename>" "metatitle": display metadata from .metadata.json files if available, fall back to the "filename" linemode if no metadata was found. See :meta command.
The custom linemodes may be added by subclassing the LinemodeBase class. See the ranger.core.linemode module for some examples.
The keys you bind with this command are accessible in the file browser only, not in the console, pager or taskview. To bind keys there, use the commands "cmap", "pmap" or "tmap".
This command is based on the scout command and supports all of its options.
:meta title The Hitchhiker's Guide to the Galaxy
:meta year 1979
This metadata can be displayed by, for example, using the "metatitle" line mode by typing Mt.
Note that if you specify an application, the mode is ignored.
Flags:
-a Position before all extensions
-r Remove everything before extensions
Flags:
-a Automatically open a file on unambiguous match
-e Open the selected file when pressing enter
-f Filter files that match the current search pattern
-g Interpret pattern as a glob pattern
-i Ignore the letter case of the files
-k Keep the console open when changing a directory with the command
-l Letter skipping; e.g. allow "rdme" to match the file
"readme"
-m Mark the matching files after pressing enter
-M Unmark the matching files after pressing enter
-p Permanent filter: hide non-matching files after pressing enter
-r Interpret pattern as a regular expression pattern
-s Smart case; like -i unless pattern contains upper case letters
-t Apply filter and search pattern as you type
-v Inverts the match
Multiple flags can be combined. For example, ":scout -gpt" would create a :filter-like command using globbing.
This command is based on the scout command and supports all of its options.
This command is based on the scout command and supports all of its options.
setting type | example values
---------------+----------------------------
bool | true, false
integer | 1, 23, 1337
string | foo, hello world
list | 1,2,3,4
none | none
For example, to change the sorting order in your downloads directory, tag it with the v tag by typing "v, then use this command:
setintag v sort ctime
path is a regular expression. This means that "path=~/dl" applies to all paths that start with ~/dl, e.g. ~/dl2 and ~/dl/foo. To avoid this, use "path=~/dl$".
path can be quoted with either single or double quotes to prevent unwanted splitting. path='~/dl dl$' or path="~/dl dl$"
This can be used to re-evaluate the rc.conf file after changing it:
map X chain shell vim -p %confdir/rc.conf %rangerdir/config/rc.conf; \
source %confdir/rc.conf
This command is based on the scout command and supports all of its options.
This command is based on the scout command and supports all of its options.
ranger reads several configuration files which are located in $HOME/.config/ranger or $XDG_CONFIG_HOME/ranger if $XDG_CONFIG_HOME is defined. You can use the --copy-config option to obtain the default configuration files. The files contain further documentation.
rc.conf, commands.py and colorschemes do not need to be copied fully as they will only be adding to the default configuration files except if explicitly overridden. This may lead to some confusing situations, for example when a key is being bound despite the corresponding line being removed from the user's copy of the configuration file. This behavior may be disabled with an environment variable (see also: ENVIRONMENT). Note: All other configuration files only read from one source; i.e. default OR user, not both. rc.conf and commands.py are additionally read from /etc/ranger if they exist for system-wide configuration, user configuration overrides system configuration which overrides the default configuration.
When starting ranger with the --clean option, it will not access or create any of these files.
These environment variables have an effect on ranger:
Using PYTHONOPTIMIZE=1 (like python -O) will make python discard assertion statements. You will gain efficiency at the cost of losing some debug info.
Using PYTHONOPTIMIZE=2 (like python -OO) will additionally discard any docstrings. Using this will disable the <F1> key on commands.
There are various examples on how to extend ranger with plugins or combine ranger with other programs. These can be found in the /usr/share/doc/ranger/examples/ directory, or the doc/ranger/ that is provided along with the source code.
GNU General Public License 3 or (at your option) any later version.
ranger is maintained with the git version control system. To fetch a fresh copy, run:
git clone git@github.com:ranger/ranger.git
Report bugs here: <https://github.com/ranger/ranger/issues>
Please include as much relevant information as possible. For the most diagnostic output, run ranger like this: "PYTHONOPTIMIZE= ranger --debug"
| ranger-1.9.3 | 2019-12-31 |