# ranger: a curses file manager that treats the shell as its parent process

> A Python console file manager with vim bindings, a three column view and a file launcher called rifle that works out which program to run.

**ranger/ranger** — A VIM-inspired filemanager for the console

- Repository: https://github.com/ranger/ranger
- Website: https://ranger.fm
- Stars: 17,423 · Forks: 939
- Language: Python
- License: GPL-3.0
- Published: 2026-10-07 · Updated: 2026-10-07 · Language: en
- Canonical page: https://hysenlabs.com/projects/ranger-ranger

## Design goals stated as constraints, not aspirations

The README lists four design goals, and they explain the project's character better than any feature list. 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.

That last one is the design constraint everything else answers to. ranger is not trying to be a desktop replacement. It is a curses program whose most valuable output is a directory change applied to the shell it was launched from, which is why the feature list includes changing the directory of your shell after exiting ranger.

The feature list is short and specific: UTF-8 support, multi-column display, preview of the selected file or directory, common file operations including create, chmod, copy and delete, renaming multiple files at once, vim-like console and hotkeys, automatic file type detection, tabs, bookmarks and mouse support. For anyone arriving from `mc`, the README notes there is a multi-pane viewmode with two-pane and multipane screenshots.

## Installing through pipx, a package manager, or a clone

The README's preferred answer is a package manager, with PyPI as the fallback and a clone as the manual route.

The PyPI package is `ranger-fm`, and the README recommends `pipx` over plain pip to benefit from isolated environments, with a single command that installs and runs it in one step:

```bash
pipx run --spec ranger-fm ranger
```

A repology badge tracks how many distributions package it, which is the better answer for most systems.

The clone route is interesting because of what it says about the project's shape. The README notes that you do not have to install ranger at all, since you can simply run `ranger.py`. Installing from a clone is:

```bash
sudo make install
```

which the README says translates roughly to:

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

The `--record` flag writes `install_log.txt`, a list of every installed file, which the README points out is what you use to uninstall ranger. That is a small piece of foresight that a lot of `setup.py` based projects skip.

## rifle is the part that decides what opens a file

The README describes ranger as shipping with `rifle`, a file launcher that is good at automatically finding out which program to use for what file type. That is the component doing the real work behind the feature listed as automatically determine file types and run them with correct programs.

rifle is a separate executable with its own version, and the Makefile treats it as such with `NAME_RIFLE` and `VERSION_RIFLE` variables. The `examples/` directory includes `rifle_different_file_opener.conf` and `rifle_sxiv.sh`, which are configuration examples rather than code, which tells you rifle's behavior is meant to be edited rather than coded around.

The practical consequence is that file association in ranger is a text file with rules, checked in order, with fallbacks for when no rule matches. If you want a specific application to handle PDFs or images, that is a line in a rifle config rather than a desktop MIME database. The `optional dependencies` list makes the same point from the other direction, since several of the preview tools listed there are exactly the programs rifle ends up invoking.

## Previews are why ranger depends on so many programs

The optional dependencies section is the longest part of the README and it is really a specification of what the preview system can do.

For general usage the optional tools are `file` for determining file types, `chardet` for improved encoding detection of text files, `sudo` for the run as root feature, and `python-bidi` so right-to-left filenames display correctly for Hebrew and Arabic.

The enhanced previews come from `scope.sh`, and the list covers nearly every file type you would browse. Images use `img2txt` from caca-utils for ASCII art, or `w3mimgdisplay`, `ueberzug`, `mpv`, iTerm2, `kitty`, `terminology` or `urxvt` for real graphics, with `convert` from imagemagick to auto-rotate. SVGs use `rsvg-convert`. Video thumbnails use `ffmpeg` or `ffmpegthumbnailer`. Syntax highlighting uses `highlight`, `bat` or `pygmentize`. Archives use `atool`, `bsdtar`, `unrar` or `7zz`. HTML uses `lynx`, `w3m` or `elinks`. PDFs use `pdftotext` or `mutool` for text and `pdftoppm` for images. DjVu uses `djvutxt` and `ddjvu`. Ebooks use `calibre` or `epub-thumbnailer`.

The tail of the list is the interesting part: JSON with `python` or `jq`, SQLite tables with `sqlite3` and optionally `sqlite-utils`, Jupyter notebooks with `jupyter nbconvert`, font previews with `fontimage`, 3D models with `openscad`, draw.io diagrams, BitTorrent info with `transmission-show`, media info with `mediainfo` or `exiftool`, and OpenDocument text with `odt2txt`. Nothing here is required, but each entry is a file type you get for free once the tool is installed.

## Configuration through --copy-config and ranger/config/

ranger can copy default configuration files to `~/.config/ranger` when run with the `--copy-config` switch, and the README gives the accepted values as `rc`, `scope`, or `all`. It points at `ranger --help` for the full description of that switch and at `ranger/config/` for the defaults themselves.

Two configuration surfaces exist and the difference matters. `rc.conf` holds the settings most people edit: colors, column widths, sorting, whether the shell changes directory. `scope.sh` is the preview script, and it is the one you edit when you want a new preview type rather than a new color.

The `examples/` directory is the best documentation of the extension model, and its contents describe what people actually build. There are plugins named for automatic directory changing in fish and in plain shell, `plugin_avfs.py` for archives, `plugin_chmod_keybindings.py`, `plugin_fasd_add.py` for directory jumping, `plugin_file_filter.py`, `plugin_hello_world.py`, `plugin_ipc.py`, `plugin_linemode.py`, `plugin_new_macro.py`, `plugin_new_sorting_method.py`, and two mounting plugins, `plugin_pmount.py` and `plugin_pmount_dynamic.py`. There is also `vim_file_chooser.vim`, which uses ranger as a file chooser from inside vim.

Plugins are Python files, and `plugin_hello_world.py` being in the list tells you the project expects beginners to read it first.

## The Makefile reveals the Python support window

The requirements are stated as Python `>=2.6` or `>=3.1` with the `curses` module, optionally with wide-unicode support, plus a pager, `less` by default. A requirement that old is unusual in 2026 and worth explaining rather than repeating.

The Makefile shows what it means. There is a block that hunts for a usable interpreter, preferring `python3` and falling back to `python` or `python2`, each guarded by a version test that exits if the interpreter is older than 2.6, and it errors out with No suitable python found. if nothing matches. That is compatibility code written when Python 2 was current, and it is preserved rather than removed.

The version number is derived rather than hardcoded: `VERSION` is pulled from README.md with a grep for the first version-looking string, which is why the README header reads Ranger 1.9.4. Release tarballs are named from that value plus the first eight characters of the commit hash.

Everything else follows the conventions of a `setup.py` era project. `PREFIX` defaults to `/usr/local`, `DESTDIR` to `/`, `PYOPTIMIZE` to 1, and the default target is test plus compile. `requirements.txt` is a short development list of flake8, pylint, pytest and setuptools, and the tree carries `.flake8` and `.pylintrc` to match. The repository is GPL-3.0 with a `LICENSE` file, an `AUTHORS` file and a `HACKING.md` for development-specific information.

## Conclusion

ranger is a good fit if you already live in the keyboard and want file management that shares muscle memory with vi rather than with a mouse. Its design goals are stated plainly in the README: easy to maintain in a high level language, small and useful, one thing done well, with smooth integration into the unix shell. The integration point is the part that distinguishes it, since changing your shell's directory on exit makes it a component of your workflow rather than an application you visit. Previews are the strongest feature and also the most demanding, since `scope.sh` grows to need ffmpeg, imagemagick, bat, calibre and much more depending on what you browse. The README documents installation, the man page covers usage, and the wiki holds the official user guide and FAQ. The repository's last push was on 2026-09-09 and the README header reads Ranger 1.9.4.

## FAQ

### What is ranger, the console file manager?

It is a Python curses file manager with vim key bindings, described in the README as a minimalistic interface with a view on the directory hierarchy. The columns run parent directory, current directory and a preview of the selected file. It ships with rifle, a launcher that works out which program should open a given file type, and it can change your shell's directory when it exits.

### How do I install ranger without a package manager?

Clone the repository and either run ranger.py directly or install it. The README notes you do not have to install at all, since you can simply run ranger.py. Installing is sudo make install, which the README says translates roughly to sudo python setup.py install --optimize=1 --record=install_log.txt, and the record flag writes install_log.txt listing every installed file so you can uninstall later.

### How do I configure ranger after installing it?

Run it with the --copy-config switch, which accepts rc, scope or all, and it copies the defaults into ~/.config/ranger. The defaults themselves are in ranger/config/. Settings live in rc.conf, while preview behavior lives in scope.sh, which is the script that decides which external tool previews which file type.

### What external tools does ranger need for file previews?

None are required, and each one unlocks a file type. The README lists image previews through img2txt or a graphics-capable terminal, video thumbnails through ffmpeg, syntax highlighting through highlight, bat or pygmentize, archives through bsdtar, unrar or 7zz, PDF text through pdftotext or mutool, ebooks through calibre, SQLite through sqlite3, notebooks through jupyter nbconvert and 3D models through openscad.

## Sources

- [Issues](https://github.com/ranger/ranger/issues)
- [License: GPL-3.0](https://github.com/ranger/ranger/blob/master/LICENSE)
- [Project website](https://ranger.fm)
- [ranger/ranger on GitHub](https://github.com/ranger/ranger)
- [README](https://github.com/ranger/ranger/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/ranger-ranger