Scroll to navigation

kitten-choose-files(1) kitty kitten-choose-files(1)

Name

kitten-choose-files - Choose files, fast

Overview

Added in version 0.43.0.

The choose-files kitten is designed to allow you to select files, very fast, with just a few key strokes. It operates like fzf and similar fuzzy finders, except that it is specialised for finding files. As such it supports features such as filtering by file type, file type icons, content previews (coming soon) and so on, out of the box. It can be used as a drop in (but much more efficient and keyboard friendly) replacement for the File open and save dialog boxes common to GUI programs. On Linux, with the help of the desktop-ui kitten, you can even convince most GUI programs on your computer to use this kitten instead of regular file dialogs.

Simply run it as:

kitten choose-files


to select a single file from the tree rooted at the current working directory.

Configuration

You can configure various aspects of the kitten's operation by creating a choose-files.conf in your kitty config folder. See below for the supported configuration directives.

Filesystem scanning


show_hidden last


Whether to show hidden files. The default value of last means remember the last used value. This setting can be toggled withing the program.


sort_by_last_modified last


Whether to sort the list of entries by last modified, instead of name. Note that sorting only applies before any query is entered. Once a query is entered entries are sorted by their matching score. The default value of last means remember the last used value. This setting can be toggled withing the program.


respect_ignores last


Whether to respect .gitignore and .ignore files and the ignore setting. The default value of last means remember the last used value. This setting can be toggled withing the program.


An ignore pattern to ignore matched files. Uses the same sytax as .gitignore files (see man gitignore). Anchored patterns match with respect to whatever directory is currently being displayed. Can be specified multiple times to use multiple patterns. Note that every pattern has to be checked against every file, so use sparingly.

Keyboard shortcuts


map esc quit
map ctrl+c quit




map enter accept




map shift+enter select


When selecting multiple files, this will add the current file to the list of selected files. You can also toggle the selected status of a file by holding down the Ctrl key and clicking on it. Similarly, the Alt key can be held to click and extend the range of selected files.


map ctrl+enter typename


Type a file name/path rather than filtering the list of existing files. Useful when specifying a file name for saving that does not yet exist. Does not work when selecting files to open rather than to save.


map down next 1




map up next -1




map left next left




map right next right




map home next first_on_screen
map ctrl+home next first




map end next last_on_screen
map ctrl+end next last




map tab cd current




map shift+tab cd up




map ctrl+/ cd /




map ctrl+~ cd ~
map ctrl+` cd ~
map ctrl+shift+` cd ~




map ctrl+t cd /tmp




map ctrl+f 1




map alt+f -1




map alt+h toggle dotfiles




map alt+d toggle ignorefiles




map alt+d toggle sort_by_dates


Source code for choose_files

The source code for this kitten is available on GitHub.

Command line interface

kitten choose_files [options] [directory to start choosing files in]


Select one or more files, quickly, using fuzzy finding, by typing just a few characters from the file name. Browse matching files, using the arrow keys to navigate matches and press Enter to select. The Tab key can be used to change to a sub-folder. See the online docs for full details.

Options

The type of object(s) to select Default: file Choices: dir, dirs, file, files, save-dir, save-file, save-files

A list of filters to restrict the displayed files. Can be either mimetypes, or glob style patterns. Can be specified multiple times. The syntax is type:expression:Descriptive Name. For example: mime:image/png:Images and mime:image/gif:Images and glob:*.[tT][xX][Tt]:Text files. Note that glob patterns are case-sensitive. The mimetype specification is treated as a glob expressions as well, so you can, for example, use mime:text/* to match all text files. The first filter in the list will be applied by default. Use a filter such as glob:*:All to match all files. Note that filtering only appies to files, not directories.

A suggested name when picking a save file.

Path to an existing file to use as the save file.

Window title to use for this chooser

Override individual configuration options, can be specified multiple times. Syntax: name=value.

Specify a path to the configuration file(s) to use. All configuration files are merged onto the builtin choose-files.conf, overriding the builtin values. This option can be specified multiple times to read multiple configuration files in sequence, which are merged. Use the special value NONE to not load any config file.

If this option is not specified, config files are searched for in the order: $XDG_CONFIG_HOME/kitty/choose-files.conf, ~/.config/kitty/choose-files.conf, $XDG_CONFIG_DIRS/kitty/choose-files.conf. The first one that exists is used as the config file.

If the environment variable KITTY_CONFIG_DIRECTORY is specified, that directory is always used and the above searching does not happen.

If /etc/xdg/kitty/choose-files.conf exists, it is merged before (i.e. with lower priority) than any user config files. It can be used to specify system-wide defaults for all users. You can use either - or /dev/stdin to read the config from STDIN.


Path to a file to which the output is written in addition to STDOUT.

The format in which to write the output. Default: text Choices: json, text

Path to a file to which to write the process ID (PID) of this process to.

Author

Kovid Goyal

Copyright

2025, Kovid Goyal

September 27, 2025 0.42.2