ranger is a console file manager with VI key bindings.  It provides a
minimalistic and nice curses interface with a view on the directory hierarchy.
It ships with rifle, a file launcher that is good at automatically finding
out which program to use for what file type.

screenshot

For mc aficionados there's also the multi-pane viewmode.

two panes
multiple panes

This file describes ranger and how to get it to run.  For instructions on the
usage, please read the man page (man ranger in a terminal).  See HACKING.md
for development-specific information.

For configuration, check the files in ranger/config/ or copy the
default config to ~/.config/ranger with ranger --copy-config
(see instructions).

The examples/ directory contains several scripts and plugins that demonstrate how
ranger can be extended or combined with other programs.  These files can be
found in the git repository or in /usr/share/doc/ranger.

A note to packagers: Versions meant for packaging are listed in the changelog
on the website.

About

Design Goals

  • An easily maintainable file manager in a high level language
  • A quick way to switch directories and browse the file system
  • Keep it small but useful, do one thing and do it well
  • Console-based, with smooth integration into the unix shell

Features

  • UTF-8 Support  (if your Python copy supports it)
  • Multi-column display
  • Preview of the selected file/directory
  • Common file operations (create/chmod/copy/delete/...)
  • Renaming multiple files at once
  • VIM-like console and hotkeys
  • Automatically determine file types and run them with correct programs
  • Change the directory of your shell after exiting ranger
  • Tabs, bookmarks, mouse support...

Dependencies

  • Python (>=2.6 or >=3.1) with the curses module
    and (optionally) wide-unicode support
  • A pager (less by default)

Optional dependencies

For general usage:

  • file for determining file types
  • chardet (Python package) for improved encoding detection of text files
  • sudo to use the "run as root" feature
  • python-bidi (Python package) to display right-to-left file names correctly
    (Hebrew, Arabic)

For enhanced file previews (with scope.sh):

  • img2txt (from caca-utils) for ASCII-art image previews
  • w3mimgdisplay, ueberzug, mpv, iTerm2, kitty, terminology or urxvt for image previews
  • convert (from imagemagick) to auto-rotate images and for image previews
  • rsvg-convert (from librsvg)
    for SVG previews
  • ffmpeg, or ffmpegthumbnailer for video thumbnails
  • highlight, bat or pygmentize for syntax highlighting of code
  • atool, bsdtar, unrar and/or 7z to preview archives
  • bsdtar, tar, unrar, unzip and/or zipinfo (and sed) to preview
    archives as their first image
  • lynx, w3m or elinks to preview html pages
  • pdftotext or mutool (and fmt) for textual pdf previews, pdftoppm to
    preview as image
  • djvutxt for textual DjVu previews, ddjvu to preview as image
  • calibre or epub-thumbnailer for image previews of ebooks
  • transmission-show for viewing BitTorrent information
  • mediainfo or exiftool for viewing information about media files
  • odt2txt for OpenDocument text files (odt, ods, odp and sxw)
  • python or jq for JSON files
  • sqlite3 for listing tables in SQLite database (and optionally sqlite-utils for fancier box drawing.)
  • jupyter nbconvert for Jupyter Notebooks
  • fontimage for font previews
  • openscad for 3D model previews (stl, off, dxf, scad, csg)
  • draw.io for draw.io diagram previews
    (drawio extension)

Installing

Use the package manager of your operating system to install ranger.
You can also install ranger through PyPI: pip install ranger-fm.
However, it is recommended to use pipx instead
(to benefit from isolated environments). Use
pipx run --spec ranger-fm ranger to install and run ranger in one step.

Installing from a clone

Note that you don't have to install ranger; you can simply run ranger.py.

To install ranger manually:

sudo make install

This translates roughly to:

sudo python setup.py install --optimize=1 --record=install_log.txt

This also saves a list of all installed files to install_log.txt, which you can
use to uninstall ranger.

Getting Started

After starting ranger, you can use the Arrow Keys or h j k l to
navigate, Enter to open a file or q to quit.  The third column shows a
preview of the current file.  The second is the main column and the first shows
the parent directory.

Ranger can automatically copy default configuration files to ~/.config/ranger
if you run it with the switch --copy-config=( rc | scope | ... | all ).
See ranger --help for a description of that switch.  Also check
ranger/config/ for the default configuration.

Going Further

  • To get the most out of ranger, read the Official User Guide.
  • For frequently asked questions, see the FAQ.
  • For more information on customization, see the wiki.

Community

For help, support, or if you just want to hang out with us, you can find us here:

License

  • GPL-3.0 license

Resources