---
id: iterfzf
version: "1.9.0.67.0"
license: GPL-3.0-or-later
license_treatment: copyleft
maintenance: aging
---

# iterfzf — Pythonic interface to fzf

License: copyleft · Maintenance: aging · Downloads: 690.2K/mo

## What it is and what it does

iterfzf wraps the fzf command-line fuzzy finder in a Pythonic API that consumes iterables lazily rather than requiring a complete list upfront. This design enables immediate display of items as they arrive, making it particularly useful when data is streamed from network sources or generated on-demand. The package bundles prebuilt fzf binaries for major platforms (macOS, Linux, Windows), so installation via pip includes everything needed without requiring separate fzf setup.

The core function, iterfzf(), accepts an iterable of strings and displays them interactively, returning the user's selection(s) or raising KeyboardInterrupt if cancelled. It supports both single and multi-selection modes, fuzzy and exact matching, ANSI colors, custom key bindings, tmux integration, and numerous fzf options passed as keyword arguments. It handles both Unicode and byte strings, respects encoding parameters, and can process multi-line items using NUL-character separation.

Use it for:

- Build interactive CLI tools that let users pick from dynamically generated or streamed lists without buffering all items first.
- Create shell-like selection interfaces in Python scripts where users interactively choose from search results or file listings.
- Integrate fuzzy finding into data pipelines where selections feed into downstream processing steps.
- Implement terminal-based configuration or menu systems with live search and filtering.
- Process multi-line or complex text data interactively with NUL-separated I/O for safe delimiter handling.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a Python interface to fzf, a command-line fuzzy finder, allowing interactive selection from iterables with lazy consumption and immediate display of streamed data.

Yes, with conditions. Install if you need interactive fuzzy selection in Python and can accept GPLv3 licensing constraints. The bundled fzf binaries eliminate setup friction on common platforms, and zero runtime dependencies make integration straightforward. However, aging maintenance (last release 201 days ago) and platform-specific wheel availability mean you should verify fzf binary support for your target platform and monitor for security updates to the bundled fzf version.

## Install

pip install iterfzf
uv add iterfzf
poetry add iterfzf

## Installing iterfzf

Before you install: Medium install friction due to platform-specific wheels, but prebuilt fzf binaries are bundled for common platforms (macOS, Linux, Windows on x86_64 and ARM), eliminating external dependencies. Last release was 201 days ago; maintenance status is aging but the repository remains active and not archived.

License in practice: Licensed under GPL-3.0-or-later (copyleft). Any code that imports and uses iterfzf in a distributed application must comply with GPLv3 obligations, including source code disclosure if the application is distributed.

Quickstart:

pip install iterfzf

from iterfzf import iterfzf

result = iterfzf(['apple', 'banana', 'cherry'])
print(result)  # returns the user's selection

Requires fzf binary available at runtime; bundled wheels provide this for common platforms, but FreeBSD and other minor platforms require manual fzf installation.

Verify before relying:

- Whether the bundled fzf binary versions are kept current with upstream fzf security patches.
- Performance characteristics when streaming very large iterables over slow network connections.
- Compatibility with non-standard terminal emulators or restricted shell environments.

## Package facts

- License: GPL-3.0-or-later (copyleft)
- Python support: supports_current
- Install friction: medium
- Maintenance: aging
- Downloads: 690.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

fzf python interface, interactive fuzzy selection, command-line picker, lazy iterable selection, terminal ui selection tool, streaming data picker, interactive list selector, interactive-cli, fuzzy-finder, user-selection

[View on SkillFed](https://skillfed.io/packages/iterfzf) · [View on PyPI](https://pypi.org/project/iterfzf/)