iterfzf: Pythonic interface to fzf

.. image:: https://img.shields.io/pypi/v/iterfzf :target: https://pypi.org/project/iterfzf/ :alt: Latest PyPI version

.. image:: https://github.com/dahlia/iterfzf/actions/workflows/test.yaml/badge.svg :alt: Build status (GitHub Actions) :target: https://github.com/dahlia/iterfzf/actions/workflows/test.yaml

Demo session

.. image:: https://asciinema.org/a/121028.png :target: https://asciinema.org/a/121028 :alt: iterfzf demo session

See also the API reference_.

Key features

• No dependency but only Python is required. Prebuilt fzf binary for each platform is bundled into wheels. Everything is ready by pip install iterfzf. (Note that not wheels of all supported platforms are uploaded to PyPI as they don't allow minor platforms e.g. FreeBSD. The complete wheels can be found from the GitHub releases__.)
• Consumes an iterable rather than a list. It makes UX way better when the input data is long but streamed from low latency network. It can begin to display items immediately after only part of items are ready, and before the complete items are ready.
• Supports Python 3.8 or higher.

__ https://github.com/dahlia/iterfzf/releases

.. _api reference:

iterfzf.iterfzf(iterable, *, **options)

Consumes the given iterable of strings, and displays them using fzf. If a user chooses something it immediately returns the chosen things. If the user cancels the selection, the KeywordInterrupt exception will be raised.

The following is the full list of parameters. Pass them as keyword arguments except for iterable which comes first:

iterable (required) The only required parameter. Every element which this iterable yields is displayed immediately after each one is produced. In other words, the passed iterable is lazily consumed.

It can be an iterable of byte strings (e.g. [b'foo', b'bar']) or of Unicode strings (e.g. [u'foo', u'bar']), but must not be mixed (e.g. [u'foo', b'bar']). If they are byte strings the function returns bytes. If they are Unicode strings it returns Unicode strings. See also the encoding parameter.

.. list-table:: Keyword arguments :widths: 12 12 12 50 :header-rows: 1

• • Keyword
  • Default
  • CLI option
  • Description

• • ansi

  • None

  • --ansi

  • True to enable ansi colors mode.

    New in version 1.0.0.

• • bind

  • --bind

  • The key/event bindings to pass to fzf.

    Dictionary of the form {KEY: ACTION} or {EVENT: ACTION}.

    New in version 1.4.0.

• • case_sensitive

  • None

  • --smart-case

  • True for case sensitivity, and False for case insensitivity. None, the default, for smart-case match.

    True corresponds to +i option and False corresponds to -i option.

• • color

  • None

  • --color

  • Accepts color scheme name or a dictionary in the form of {element: color}.

    New in version 1.6.0.

• • cycle

  • False

  • --cycle

  • True to enable cycling scrolling.

    New in version 1.1.0.

• • encoding
  • sys.getdefaultencoding()
  • --encoding
  • The text encoding name (e.g. 'utf-8', 'ascii') to be used for encoding iterable values and decoding return values. It's ignored when the iterable values are byte strings.
• • exact
  • False
  • --exact
  • False for fuzzy matching, and True for exact matching.

• • extended

  • True

  • --extended --no-extended

  • True for extended-search mode. False to turn it off.

    True corresponds to -x/--extended option, and False corresponds to +x/--no-extended option.

• • header

  • None

  • --header

  • Sticky header printed below prompt.

    New in version 1.6.0.

• • mouse
  • True
  • --no-mouse
  • False to disable mouse.

• • multi

  • False

  • --multi

  • True to let the user to choose more than one. A user can select items with tab/shift-tab. If multi=True the function returns a list of strings rather than a string.

    False to make a user possible to choose only one. If multi=False it returns a string rather than a list.

    For both modes, the function returns None if nothing is matched.

• • preview
  • None
  • --preview
  • New in version 0.5.0.

• • print_query

  • False

  • --print-query

  • If True the return type is a tuple where the first element is the query the user actually typed, and the second element is the selected output as described above and depending on the state of multi.

    New in version 0.3.0.

• • prompt
  • " >"
  • --prompt
• • query
  • "" (empty string)
  • --query
  • The query string to be filled at first. (It can be removed by a user.)

• • read0

  • False

  • --read0 --print0

  • True to enable NUL character (\0) separated I/O for processing multi-line items. When enabled, items may contain newlines (CR/LF), but must not contain NUL characters. Both --read0 (for input) and --print0 (for output) are passed to fzf.

    New in version 1.9.0.

• • sort

  • False

  • --sort

  • Sorts the result if True. False by default.

    New in version 1.3.0.

• • tmux

  • False

  • --tmux[=OPTS]

  • Start fzf in a tmux popup if tmux=True or the config string is provided (requires tmux 3.3+).

    The format of the option is like [center|top|bottom|left|right][,SIZE[%]][,SIZE[%]][,border-native] (default: center,50%).

    New in version 1.7.0.

• • __extra__

  • []

  • The iterable of extra raw options/arguments to pass to fzf.

    This is how you pass extra options that are not already defined as keyword arguments.

    New in version 1.1.0.

Author and license

The iterfzf library is written by Hong Minhee__ and distributed under GPLv3_ or later.

The fzf program is written by Junegunn Choi__ and distributed under MIT license.

__ https://hongminhee.org/ .. _GPLv3: https://www.gnu.org/licenses/gpl-3.0.html __ https://junegunn.kr/

Changelog

Versioning scheme

Note that ``iterfzf`` does *not* follow `Semantic Versioning`_.  The version
consists of its own major and minor number followed by the version of bundled
``fzf``.  For example, 1.2.3.4.5 means that ``iterfzf``'s own major version
is 1, and its own minor version is 2, plus the version of ``fzf`` it bundles
is 3.4.5.

.. code-block:: text

   /---------- 1. iterfzf's major version
   |   /------ 3. bundled fzf's major version
   |   |   /-- 5. bundled fzf's patch version
   |   |   |
   v   v   v
   1.2.3.4.5
     ^   ^
     |   |
     |   \---- 4. bundled fzf's minor version
     \-------- 2. iterfzf's minor version

.. _Semantic Versioning: http://semver.org/


Version 1.10.0.67.0

To be released. Bundles fzf 0.67.0__.

__ https://github.com/junegunn/fzf/releases/tag/v0.67.0

Version 1.9.0.67.0

Released on January 25, 2026.   Bundles ``fzf`` `0.67.0`__.

- Added ``read0`` option for processing multi-line items using NUL character
  separation.  [`#46`__]
- Officially support Python 3.14.

__ https://github.com/junegunn/fzf/releases/tag/v0.67.0
__ https://github.com/dahlia/iterfzf/issues/46


Version 1.8.0.62.0

Released on May 15, 2025. Bundles fzf 0.62.0__.

• Fixed an error when the iterfzf() function was invoked with the tmux=True option. [#45__ by Peter Rebrun]

__ https://github.com/junegunn/fzf/releases/tag/v0.62.0 __ https://github.com/dahlia/iterfzf/pull/45

Version 1.7.0.62.0

Released on May 10, 2025.  Bundles ``fzf`` `0.62.0`__.

- Added ``tmux`` option.  [`#44`__ by Peter Rebrun]

__ https://github.com/junegunn/fzf/releases/tag/v0.62.0
__ https://github.com/dahlia/iterfzf/pull/44


Version 1.6.0.60.3

Released on March 11, 2025. Bundles fzf 0.60.3__.

• Added header option. [#42__ by Phred Lane]
• Added color option. [#43__ by Phred Lane]

__ https://github.com/junegunn/fzf/releases/tag/v0.60.3 __ https://github.com/dahlia/iterfzf/pull/42 __ https://github.com/dahlia/iterfzf/pull/43

Version 1.5.0.60.2

Released on March 5, 2025.  Bundles ``fzf`` `0.60.2`__.

- Added support for raising ``KeyboardInterrupt``.  [`#40`__ by Phred Lane]
- Officially support Python 3.13.

__ https://github.com/junegunn/fzf/releases/tag/v0.60.2
__ https://github.com/dahlia/iterfzf/pull/40


Version 1.4.0.60.2

Released on March 1, 2025. Bundles fzf 0.60.2__.

__ https://github.com/junegunn/fzf/releases/tag/v0.60.2

Version 1.4.0.54.3

Released on August 24, 2024.  Bundles ``fzf`` `0.54.3`__.

__ https://github.com/junegunn/fzf/releases/tag/v0.54.3


Version 1.4.0.51.0

Released on May 7, 2024. Bundles fzf 0.51.0__.

• Added bind option. [#21, #36 by Gregory.K]

__ https://github.com/junegunn/fzf/releases/tag/0.51.0 __ https://github.com/dahlia/iterfzf/issues/21 __ https://github.com/dahlia/iterfzf/pull/36

Version 1.3.0.51.0

Released on May 6, 2024.  Bundles ``fzf`` `0.51.0`__.

- Adde