README.md

   1 ranger 1.9.2
   2 ============
   3
   4 [![Build Status](https://travis-ci.org/ranger/ranger.svg?branch=master)](https://travis-ci.org/ranger/ranger)
   5 <a href="https://repology.org/metapackage/ranger/versions">
   6   <img src="https://repology.org/badge/latest-versions/ranger.svg" alt="latest packaged version(s)">
   7 </a>
   8
   9 ranger is a console file manager with VI key bindings.  It provides a
  10 minimalistic and nice curses interface with a view on the directory hierarchy.
  11 It ships with `rifle`, a file launcher that is good at automatically finding
  12 out which program to use for what file type.
  13
  14 ![screenshot](https://raw.githubusercontent.com/ranger/ranger-assets/master/screenshots/screenshot.png)
  15
  16 For `mc` aficionados there's also the multi-pane viewmode.
  17
  18 <p>
  19 <img src="https://raw.githubusercontent.com/ranger/ranger-assets/master/screenshots/twopane.png" alt="two panes" width="49%" />
  20 <img src="https://raw.githubusercontent.com/ranger/ranger-assets/master/screenshots/multipane.png" alt="multiple panes" width="49%" />
  21 </p>
  22
  23 This file describes ranger and how to get it to run.  For instructions on the
  24 usage, please read the man page (`man ranger` in a terminal).  See `HACKING.md`
  25 for development-specific information.
  26
  27 For configuration, check the files in `ranger/config/` or copy the
  28 default config to `~/.config/ranger` with `ranger --copy-config`
  29 (see [instructions](#getting-started)).
  30
  31 The `examples/` directory contains several scripts and plugins that demonstrate how
  32 ranger can be extended or combined with other programs.  These files can be
  33 found in the git repository or in `/usr/share/doc/ranger`.
  34
  35 A note to packagers: Versions meant for packaging are listed in the changelog
  36 on the website.
  37
  38
  39 About
  40 -----
  41 * Authors:     see `AUTHORS` file
  42 * License:     GNU General Public License Version 3
  43 * Website:     https://ranger.github.io/
  44 * Download:    https://ranger.github.io/ranger-stable.tar.gz
  45 * Bug reports: https://github.com/ranger/ranger/issues
  46 * git clone    https://github.com/ranger/ranger.git
  47
  48
  49 Design Goals
  50 ------------
  51 * An easily maintainable file manager in a high level language
  52 * A quick way to switch directories and browse the file system
  53 * Keep it small but useful, do one thing and do it well
  54 * Console-based, with smooth integration into the unix shell
  55
  56
  57 Features
  58 --------
  59 * UTF-8 Support  (if your Python copy supports it)
  60 * Multi-column display
  61 * Preview of the selected file/directory
  62 * Common file operations (create/chmod/copy/delete/...)
  63 * Renaming multiple files at once
  64 * VIM-like console and hotkeys
  65 * Automatically determine file types and run them with correct programs
  66 * Change the directory of your shell after exiting ranger
  67 * Tabs, bookmarks, mouse support...
  68
  69
  70 Dependencies
  71 ------------
  72 * Python (`>=2.6` or `>=3.1`) with the `curses` module
  73   and (optionally) wide-unicode support
  74 * A pager (`less` by default)
  75
  76 Optional:
  77
  78 * The `file` program for determining file types
  79 * `chardet` (Python package) for improved encoding detection of text files
  80 * `sudo` to use the "run as root" feature
  81 * `python-bidi` for correct display of RTL file names (Hebrew, Arabic)
  82
  83 Optional, for enhanced file previews (with `scope.sh`):
  84
  85 * `img2txt` (from `caca-utils`) for ASCII-art image previews
  86 * `w3mimgdisplay`, `ueberzug`, `kitty`, `terminology` or `urxvt` for image
  87   previews
  88 * `convert` (from `imagemagick`) to auto-rotate images and for SVG previews
  89 * `ffmpegthumbnailer` for video thumbnails
  90 * `highlight` or `pygmentize` for syntax highlighting of code
  91 * `atool`, `bsdtar`, `unrar` and/or `7z` for previews of archives
  92 * `bsdtar`, `tar`, `unrar` and/or `unzip` to preview archives as their first
  93   image
  94 * `lynx`, `w3m` or `elinks` for previews of html pages
  95 * `pdftotext` or `mutool` for textual `pdf` previews, `pdftoppm` to preview as
  96   image
  97 * `djvutxt` for textual DjVu previews, `ddjvu` to preview as image
  98 * `calibre` or `epub-thumbnailer` for image previews of ebooks
  99 * `transmission-show` for viewing BitTorrent information
 100 * `mediainfo` or `exiftool` for viewing information about media files
 101 * `odt2txt` for OpenDocument text files (`odt`, `ods`, `odp` and `sxw`)
 102 * `python` or `jq` for JSON files
 103 * `fontimage` for font previews
 104
 105 Installing
 106 ----------
 107 Use the package manager of your operating system to install ranger.
 108 You can also install ranger through PyPI: ```pip install ranger-fm```.
 109
 110 <details>
 111   <summary>
 112     Check current version:
 113     <sub>
 114       <a href="https://repology.org/metapackage/ranger/versions">
 115         <img src="https://repology.org/badge/tiny-repos/ranger.svg" alt="Packaging status">
 116       </a>
 117     </sub>
 118   </summary>
 119   <a href="https://repology.org/metapackage/ranger/versions">
 120     <img src="https://repology.org/badge/vertical-allrepos/ranger.svg" alt="Packaging status">
 121   </a>
 122 </details>
 123
 124 ### Installing from a clone
 125 Note that you don't *have* to install ranger; you can simply run `ranger.py`.
 126
 127 To install ranger manually:
 128 ```
 129 sudo make install
 130 ```
 131
 132 This translates roughly to:
 133 ```
 134 sudo python setup.py install --optimize=1 --record=install_log.txt
 135 ```
 136
 137 This also saves a list of all installed files to `install_log.txt`, which you can
 138 use to uninstall ranger.
 139
 140
 141 Getting Started
 142 ---------------
 143 After starting ranger, you can use the Arrow Keys or `h` `j` `k` `l` to
 144 navigate, `Enter` to open a file or `q` to quit.  The third column shows a
 145 preview of the current file.  The second is the main column and the first shows
 146 the parent directory.
 147
 148 Ranger can automatically copy default configuration files to `~/.config/ranger`
 149 if you run it with the switch `--copy-config=( rc | scope | ... | all )`.
 150 See `ranger --help` for a description of that switch.  Also check
 151 `ranger/config/` for the default configuration.
 152
 153
 154 Going Further
 155 ---------------
 156 * To get the most out of ranger, read the [Official User Guide](https://github.com/ranger/ranger/wiki/Official-user-guide).
 157 * For frequently asked questions, see the [FAQ](https://github.com/ranger/ranger/wiki/FAQ%3A-Frequently-Asked-Questions).
 158 * For more information on customization, see the [wiki](https://github.com/ranger/ranger/wiki).
 159
 160
 161 Community
 162 ---------------
 163 For help, support, or if you just want to hang out with us, you can find us here:
 164 * **IRC**: channel **#ranger** on [freenode](https://freenode.net/kb/answer/chat)
 165 * **Reddit**: [r/ranger](https://www.reddit.com/r/ranger/)