iterfzf

library1.9.0.67.0pypypi✓ verified 84d ago

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.

devops

pip install iterfzf

github ↗package ↗

INSTALL

IMPORT

SIG · ITERFZF

iterfzf

devopspythonv1.9.0.67.0

Install

1.6s avg

Import

33ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.9.0.67.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.034s · 26.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.6s · import 0.031s · 23MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

iterfzf

✓ from iterfzf import iterfzf

KeywordInterrupt

✓ from iterfzf import KeywordInterrupt

✗ import iterfzf; # KeywordInterrupt not directly accessible

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

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}")

Debug

Known issues

breakingPython 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`).

affects: >=1.0.0.42.0

breakingAll 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.

affects: >=1.0.0.42.0

gotchaThe 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()]`).

affects: All versions

gotchaIf 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.

affects: All versions

gotchaiterfzf 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.

affects: All versions

Errors

Common errors & fixes

AttributeError: 'tuple' object has no attribute 'encode'

The `iterfzf` function received an iterable containing non-string elements (like tuples from `dict.items()`) or a mix of Unicode and byte strings, but it expects a uniform iterable of either Unicode or byte strings.

fix

Ensure all elements in the input iterable are consistently of `str` (Unicode) or `bytes` type. If working with dictionary items, convert them to strings (e.g., `[f'{k}: {v}' for k, v in d.items()]`).

TypeError: iterfzf() takes 1 positional argument but X were given

Since version 1.0.0.42.0, all parameters to `iterfzf()` except the initial `iterable` became keyword-only. Passing options like `multi`, `header`, or `prompt` as positional arguments will raise a `TypeError`.

fix

Pass all `iterfzf()` options as keyword arguments (e.g., `iterfzf(items, multi=True)` instead of `iterfzf(items, True)`).

Unhandled iterfzf.KeywordInterrupt

The user cancelled the selection in the `fzf` interface (e.g., by pressing Escape), and the `KeywordInterrupt` exception raised by `iterfzf` was not caught.

fix

Wrap calls to `iterfzf` in a `try...except iterfzf.KeywordInterrupt:` block to gracefully handle user cancellations. You may also need to `from iterfzf import KeywordInterrupt`.

Upgrade

Version history

1.9.0.67.0latest on PyPI · released Jan 25, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/dahlia/iterfzf ↗

packagehttps://pypi.org/project/iterfzf/ ↗