iterfzf

1.9.0.67.0 · active · verified Tue Apr 14

iterfzf is a Pythonic interface to fzf, a command-line fuzzy finder. It allows consuming iterables of strings and displaying them using fzf for interactive selection, returning the user's choice(s). Notably, it consumes iterables lazily, which is efficient for large or streamed inputs. The current version is 1.9.0.67.0, released on January 24, 2026, and bundles a prebuilt fzf binary for convenience. The library supports Python 3.8 and higher.

Warnings

breaking Python 2.7, 3.5, 3.6, and 3.7 support was dropped in version 1.0.0.42.0 (released September 18, 2023). The library now officially supports Python 3.8 and higher.
Fix: Upgrade to Python 3.8 or newer, or pin iterfzf to a version less than 1.0 (e.g., `iterfzf<1.0`).
breaking All parameters to `iterfzf()` (except the initial `iterable`) became keyword-only in version 1.0.0.42.0. Passing options as positional arguments will now raise a TypeError.
Fix: Ensure all options like `multi`, `header`, `prompt`, etc., are passed as keyword arguments.
gotcha The input `iterable` must consist uniformly of either Unicode strings or byte strings; mixing these types will lead to `AttributeError` (e.g., `'tuple' object has no attribute 'encode'` if passing dictionary `items()` directly).
Fix: Ensure all elements in the iterable are consistently of `str` or `bytes` type. If working with dictionary items, convert them to strings (e.g., `[f'{k}: {v}' for k, v in d.items()]`).
gotcha If the user cancels the selection in the `fzf` interface (e.g., by pressing Escape), `iterfzf` raises a `KeywordInterrupt` exception. This exception is a subclass of `KeyboardInterrupt`.
Fix: Wrap calls to `iterfzf` in a `try...except KeywordInterrupt:` block to gracefully handle user cancellations.
gotcha iterfzf does not follow standard Semantic Versioning. Its version string `X.Y.fzf_major.fzf_minor.fzf_patch` indicates `X.Y` as the library's own version and `fzf_major.fzf_minor.fzf_patch` as the bundled `fzf` binary's version.
Fix: When checking for updates or compatibility, understand that changes to the bundled `fzf` version are reflected in the patch segment of `iterfzf`'s full version string.

Install

pip install iterfzf Install iterfzf

Imports

iterfzf
```
from iterfzf import iterfzf
```
KeywordInterrupt
```
from iterfzf import KeywordInterrupt
```
KeywordInterrupt must be explicitly imported from the iterfzf package to catch user cancellation.

Quickstart

This example demonstrates how to use `iterfzf` to present a list of items for interactive fuzzy selection. It shows how to enable multi-selection and how to catch the `KeywordInterrupt` exception if the user cancels the selection (e.g., by pressing Escape).

from iterfzf import iterfzf, KeywordInterrupt

items = [
    "apple",
    "banana",
    "cherry",
    "date",
    "elderberry",
    "fig",
    "grape",
]

try:
    # Use multi=True to allow selecting multiple items
    selected_items = iterfzf(
        items,
        multi=True,
        header="Select fruits (Tab to multi-select, Enter to confirm, Esc to cancel):",
        prompt=">> "
    )

    if selected_items:
        print("You selected:", selected_items)
    else:
        print("No items selected.")
except KeywordInterrupt:
    print("Selection cancelled by user.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →