README.md
1[](https://travis-ci.org/derf/feh)
2
3Feh – Image viewer and Cataloguer
4---
5
6feh is a light-weight, configurable and versatile image viewer.
7It is aimed at command line users, but can also be started from graphical file
8managers. Apart from viewing images, it can compile text and thumbnail
9listings, show (un)loadable files, set X11 backgrounds, and more.
10
11Features include filelists, various image sorting modes, custom action scripts,
12and image captions. feh can be controlled by configurable keyboard and mouse
13shortcuts, terminal input and signals. When no file arguments or filelists are
14specified, feh displays all files in the current directory.
15
16For more information, please refer to the [feh
17website](https://feh.finalrewind.org/) or read the [feh
18manual](https://man.finalrewind.org/1/feh/).
19
20Dependencies
21---
22
23 * Imlib2
24 * libcurl (disable with make curl=0)
25 * libpng
26 * libX11
27 * libXinerama (disable with make xinerama=0)
28
29If built with exif=1:
30
31 * libexif-dev
32 * libexif12
33
34Recommended Binaries
35---
36
37 * convert (supplied by ImageMagick, can be used to load image formats not supported by Imlib2)
38
39Installation
40---
41
42**For end users:**
43```bash
44$ make
45$ sudo make install app=1
46```
47
48**For package maintainers and users who do not want feh to install its
49icons into /usr/share:**
50```bash
51$ make
52$ sudo make install
53```
54
55**Explanation:** feh ships some icons and an X11 desktop entry, which allow it to
56be used from file managers, desktop menus and similar. However, installing
57icons to /usr/local/share/... does not seem to work reliably.
58Because of this, when using "make install app=1", feh will install its icons
59to /usr/share/..., even though they technically belong into /usr/local.
60
61[ZSH completion for
62feh](https://git.finalrewind.org/zsh/plain/etc/completions/_feh) is also
63available.
64
65Make flags
66----------
67
68feh's build process uses make flags to enable/disable optional features and
69fine-tune the build and installation process. They can be passed as **make**
70arguments or set as environment variables, like so:
71
72```bash
73make flag=bool
74make install flag=bool
75```
76or
77```bash
78export flag=bool
79make && make install
80```
81
82The following flags are respected by the makefile. A default value of **1**
83indicates that the corresponding feature is enabled by default.
84
85| Flag | Default value | Description |
86| :--- | :---: | :--- |
87| app | 0 | install icons to /usr/share, regardless of `DESTDIR` and `PREFIX`, and call gtk-update-icon-cache afterwards |
88| curl | 1 | use libcurl to view https:// and similar images |
89| debug | 0 | debug build, enables `--debug` |
90| exif | 0 | Builtin EXIF tag display support |
91| help | 0 | include help text (refers to the manpage otherwise) |
92| inotify | 0 | enable inotify, needed for `--auto-reload` |
93| stat64 | 0 | Support CIFS shares from 64bit hosts on 32bit machines |
94| verscmp | 1 | Whether your libc provides `strvercmp()`. If set to 0, feh will use an internal implementation. |
95| xinerama | 1 | Support Xinerama/XRandR multiscreen setups |
96
97For example, `make xinerama=0 debug=1` will disable Xinerama support and
98produce a debug build; libcurl and natural sorting support will remain enabled.
99
100Additionally, the standard variables `PREFIX` and `DESTDIR` are supported.
101
102**PREFIX _(default: /usr/local)_** controls where the application and its data files
103will be installed. It must be set both during `make` and `make install`.
104
105**DESTDIR _(default: empty)_** sets the installation root during "make install". It
106is mostly useful for package maintainers.
107
108**Note:** Defaults are specified in `config.mk`. It is designed so that in most
109cases, you can set environment variables instead of editing it. E.g.:
110
111```bash
112CFLAGS='-g -Os' make
113```
114```bash
115export DESTDIR=/tmp/feh PREFIX=/usr
116make && make install
117```
118
119Builtin EXIF support is maintained by Dennis Real, [here](https://github.com/reald/feh).
120
121
122Testing (non-X)
123---------------
124
125The non-X11 parts of feh can be automatically tested by running
126
127```bash
128$ make test
129```
130This requires **perl >= 5.10** and the perl module `Test::Command`. Tests are
131non-interactive and do not require a running X11, so they can safely be run on
132a headless buildserver.
133
134
135Contributing
136---
137
138Bugfixes are always welcome, just open a pull request :)
139
140Before proposing a new feature, please consider the scope of feh: It is an
141image viewer and cataloguer, not an image editor or similar. Also, its option
142list is already pretty long. Please discuss your ideas in a feature request
143before opening a pull request in this case.
144
145Please keep in mind that feh's options, key bindings and format specifiers are
146documented in two different places: The manual (man/feh.pre) and the help text
147(src/help.raw). Although the help is not compiled in by default, it should be
148kept up-to-date. On space-constrained embedded systems, it may be more useful
149than the (significantly larger) man page.
150
){kind=link}