{"id":5973,"library":"iterfzf","title":"iterfzf","description":"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.","status":"active","version":"1.9.0.67.0","language":"en","source_language":"en","source_url":"https://github.com/dahlia/iterfzf","tags":["fuzzy-finder","cli","fzf","interactive","terminal","utility"],"install":[{"cmd":"pip install iterfzf","lang":"bash","label":"Install iterfzf"}],"dependencies":[],"imports":[{"symbol":"iterfzf","correct":"from iterfzf import iterfzf"},{"note":"KeywordInterrupt must be explicitly imported from the iterfzf package to catch user cancellation.","wrong":"import iterfzf; # KeywordInterrupt not directly accessible","symbol":"KeywordInterrupt","correct":"from iterfzf import KeywordInterrupt"}],"quickstart":{"code":"from iterfzf import iterfzf, KeywordInterrupt\n\nitems = [\n    \"apple\",\n    \"banana\",\n    \"cherry\",\n    \"date\",\n    \"elderberry\",\n    \"fig\",\n    \"grape\",\n]\n\ntry:\n    # Use multi=True to allow selecting multiple items\n    selected_items = iterfzf(\n        items,\n        multi=True,\n        header=\"Select fruits (Tab to multi-select, Enter to confirm, Esc to cancel):\",\n        prompt=\">> \"\n    )\n\n    if selected_items:\n        print(\"You selected:\", selected_items)\n    else:\n        print(\"No items selected.\")\nexcept KeywordInterrupt:\n    print(\"Selection cancelled by user.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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)."},"warnings":[{"fix":"Upgrade to Python 3.8 or newer, or pin iterfzf to a version less than 1.0 (e.g., `iterfzf<1.0`).","message":"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.","severity":"breaking","affected_versions":">=1.0.0.42.0"},{"fix":"Ensure all options like `multi`, `header`, `prompt`, etc., are passed as keyword arguments.","message":"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.","severity":"breaking","affected_versions":">=1.0.0.42.0"},{"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()]`).","message":"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).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Wrap calls to `iterfzf` in a `try...except KeywordInterrupt:` block to gracefully handle user cancellations.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z","problems":[]}