[opensourcedex]

ranger is a free, open source file management & sync project written in Python and released under GPL-3.0. It has 17,405 GitHub stars, 942 forks and 896 open issues, and was last pushed 11 days ago. On this registry it ranks #11 of 26 tracked projects in File Management & Sync, with 5 head-to-head comparisons available.

What is ranger?

Ranger is a console file manager with VI key bindings, written in Python and released under the GNU General Public License version 3, for terminal users who want to browse, preview, and manipulate files without leaving a Unix shell.

What it is

Ranger is a file manager that runs inside the console and draws a minimalistic curses interface with a view on the directory hierarchy. It presents a multi-column display, supports tabs, bookmarks, and mouse input, and ships with rifle, a file launcher that automatically determines which program to use for a given file type. For users accustomed to mc, the project also offers a multi-pane viewmode. The design goals stated by the project are an easily maintainable file manager in a high-level language, a quick way to switch directories and browse the file system, and a small but useful tool that does one thing well and integrates smoothly with the Unix shell.

The concrete problem it solves is the gap between the plain shell and a full file manager. Instead of stringing together ls, cd, cp, and rm invocations, a user navigates the file system visually while staying in the terminal, and ranger can change the directory of the shell after exiting, so the browser and the shell stay in step. It sits in the Python and Unix console ecosystem, and its closest named relative is Midnight Commander, whose users ranger targets directly with its multi-pane viewmode. It replaces the piecemeal shell workflow for file operations, previews, and bulk renaming rather than replacing a graphical desktop environment.

Key capabilities

  • rifle, a file launcher that automatically finds out which program to use for what file type.
  • Preview of the selected file or directory, extended through the scope.sh script, which can call img2txt, w3mimgdisplay, ueberzug, kitty, mpv, ffmpeg, pdftotext, djvutxt, odt2txt, sqlite3, jq, and jupyter nbconvert.
  • Common file operations including create, chmod, copy, and delete, plus renaming multiple files at once.
  • VIM-like console and hotkeys, with tabs, bookmarks, and mouse support.
  • UTF-8 support, where the local Python copy supports it, with optional chardet encoding detection and python-bidi for right-to-left file names.
  • Directory change of the calling shell after exiting ranger.
  • Configuration through ranger --copy-config, which copies the defaults from ranger/config/ into ~/.config/ranger.

Who uses it and how

  • Console-centric users on Unix-like systems who want file browsing to stay inside the terminal and to hand the final directory back to their shell.
  • Users with media- and document-heavy directories, who install optional preview helpers such as w3mimgdisplay, ueberzug, mpv, or a terminal supporting the Kitty graphics protocol to render images rather than text.
  • Former Midnight Commander users, who get the multi-pane viewmode as a familiar layout.
  • Extenders and integrators, who use the examples/ directory to combine ranger with external programs; those files also ship in /usr/share/doc/ranger.
  • Packagers, since the download page and changelog explicitly list versions meant for packaging.

Getting started

Download ranger-stable.tar.gz from https://ranger.fm/, or clone the repository with git clone https://github.com/ranger/ranger.git. Usage is documented in the terminal through man ranger, and the default configuration can be copied with ranger --copy-config.

How it compares

Among the tools named in the facts, ranger's nearest comparison point is Midnight Commander, which it courts with a multi-pane viewmode while keeping VI key bindings and a curses interface as its own idiom. Compared with a plain shell, it adds a preview pane, bulk renaming, and a file launcher, at the cost of learning its console and hotkeys. It is licensed under the GNU General Public License version 3 and is distributed as source, so users run it under that licence rather than under a permissive one.

When to use it — and when not to

A self-hoster runs Python 2.6 or newer, or Python 3.1 or newer, with the curses module, plus a pager such as less by default; richer previews depend on separately installed external binaries, so the feature set tracks what is present on the machine. The project carries 896 open issues and the README defers usage guidance to the man page and configuration notes, so anyone wanting a single self-contained tutorial should look elsewhere, and anyone wanting a graphical file manager should not pick this at all.

project readme (upstream, from github) — read inline

Ranger 1.9.4

Python lints and tests latest packaged version(s) Donate via Liberapay

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 (or other terminal supporting the Kitty graphics protocol), 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 7zz 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.

Check current version: Packaging status Packaging status

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:

Frequently asked questions

Is ranger free to use?

ranger is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does ranger do?

A VIM-inspired filemanager for the console

What is ranger written in?

ranger is primarily written in Python. Its source is publicly available at https://github.com/ranger/ranger, and it has 17,405 GitHub stars.