Skip to main content
Latest PyPI version Build status (GitHub Actions)

Demo session

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.

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.

Keyword arguments

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.

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.

/---------- 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

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.

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]

Version 1.7.0.62.0

Released on May 10, 2025. Bundles fzf 0.62.0.

  • Added tmux option. [#44 by Peter Rebrun]

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]

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.

Version 1.4.0.60.2

Released on March 1, 2025. Bundles fzf 0.60.2.

Version 1.4.0.54.3

Released on August 24, 2024. Bundles fzf 0.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]

Version 1.3.0.51.0

Released on May 6, 2024. Bundles fzf 0.51.0.

  • Added sort option. [#18, #35 by Gregory.K]

  • Officially support Python 3.12.

Version 1.2.0.46.1

Released on March 6, 2024. Bundles fzf 0.46.1.

  • Close stdin before waiting to allow --select-1 to work. [#34 by Alex Wood]

Version 1.1.0.44.0

Released on November 18, 2023. Bundles fzf 0.44.0.

  • Added cycle option. [#33 by Daniele Trifirò]

  • Added __extra__ option. [#32]

Version 1.0.0.42.0

Released on September 18, 2023. Bundles fzf 0.42.0.

  • Dropped Python 2.7, 3.5, 3.6, and 3.7 supports.

  • Officially support Python 3.8, 3.9, 3.10, and 3.11.

  • Dropped FreeBSD i386, Linux i686, Linux armv8l, OpenBSD i386, and Windows 32-bit supports as fzf no longer supports them.

  • Dropped OpenBSD amd64 support.

  • Except the first parameter iterable, all parameters are enforced to be keyword-only. (Note that it’s always been the recommended way to pass options, although it was not enforced.)

  • Added ansi option. [#16 by Erik Lilja]

  • The executable parameter now takes os.PathLike instead of str, which is backward compatible.

  • Added __version__ and __fzf_version__ attributes to the module.

  • Added POSIX_EXECUTABLE_NAME and WINDOWS_EXECUTABLE_NAME attributes to the module.

  • Module attribute EXECUTABLE_NAME is now a Literal['fzf', 'fzf.exe'] type, which is backward compatible with the previous str type.

  • Module attribute BUNDLED_EXECUTABLE is now Optional[pathlib.Path] type.

Version 0.5.0.20.0

Released on February 9, 2020. Bundles fzf 0.20.0.

  • Dropped Python 2.6, 3.3, and 3.4 supports.

  • Officially support Python 3.7 (it anyway had worked though).

  • Marked the package as supporting type checking by following PEP 561.

  • Added preview option. [#6 by Marc Weistroff]

  • Fixed a bug which had raised IOError by selecting an option before finished to load all options on Windows. [#3 by Jeff Rimko]

Version 0.4.0.17.3

Released on December 4, 2017. Bundles fzf 0.17.3.

Version 0.4.0.17.1

Released on October 19, 2017. Bundles fzf 0.17.1.

  • Added missing binary wheels for macOS again. (These were missing from 0.3.0.17.1, the previous release.)

Version 0.3.0.17.1

Released on October 16, 2017. Bundles fzf 0.17.1.

  • Added print_query option. [#1 by George Kettleborough]

Version 0.2.0.17.0

Released on August 27, 2017. Bundles fzf 0.17.0.

Version 0.2.0.16.11

Released on July 23, 2017. Bundles fzf 0.16.11.

Version 0.2.0.16.10

Released on July 23, 2017. Bundles fzf 0.16.10.

Version 0.2.0.16.8

Released on June 6, 2017. Bundles fzf 0.16.8.

  • Upgraded fzf from 0.16.7 to 0.16.8.

Version 0.2.0.16.7

Released on May 20, 2017. Bundles fzf 0.16.7.

  • Made sdists (source distributions) possible to be correctly installed so that older pip, can’t deal with wheels, also can install iterfzf.

Version 0.1.0.16.7

Released on May 19, 2017. Bundles fzf 0.16.7. The initial release.

Release files for iterfzf 1.9.0.67.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for iterfzf 1.9.0.67.0
File Size Uploaded
iterfzf-1.9.0.67.0.tar.gz 2.0 MB Details

Built distributions (wheels)

Table of built distributions (wheels) for iterfzf 1.9.0.67.0
File
iterfzf-1.9.0.67.0-py3-none-win_arm64.whl Python 3 none Windows ARM64 Details
iterfzf-1.9.0.67.0-py3-none-win_amd64.whl Python 3 none Windows x86-64 Details
iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl Python 3 none Linux glibc 2.17+ IBM System/390x Details
iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl Python 3 none Linux glibc 2.17+ PowerPC 64-le Details
iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl Python 3 none Linux glibc 1.2+ x86-64, Linux glibc 2.17+ x86-64 Details
iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl Python 3 none Linux glibc 2.17+ ARM64, Linux glibc 1.2+ ARM64 Details
iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl Python 3 none macOS 11.0+ ARM64 Details
iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl Python 3 none macOS 10.7+ x86-64, macOS 10.9+ x86-64 Details

Total release size: 16.3 MB

Release files / iterfzf-1.9.0.67.0.tar.gz

Download URL iterfzf-1.9.0.67.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
9e9ddeba324a6bf7786f6033d1ed5030c2b36bce86ef63f9e76ecb84529e45ac
BLAKE2b-256 checksum
How to use checksums
4c5ad955b2ee27ffc7bf48fcb99201e071a39bc68aaa3c3daf4fd4e487b7d21d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-win_arm64.whl

Download URL iterfzf-1.9.0.67.0-py3-none-win_arm64.whl
Size 1.8 MB
Tags Python 3 Windows ARM64
SHA-256 checksum
How to use checksums
8ef635f31ae30926a15da944bc8236a31805b7944d06875039998f74b52012cf
BLAKE2b-256 checksum
How to use checksums
bf5f4ceb4486a4ab699624be2caa8cdebdfce463ae5906e5511ce52bbcc8621d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-win_amd64.whl

Download URL iterfzf-1.9.0.67.0-py3-none-win_amd64.whl
Size 2.0 MB
Tags Python 3 Windows x86-64
SHA-256 checksum
How to use checksums
7b4ad3cc6a2e395970be81fb913840ff482b6d9938ecec605e4a6fce9db936fb
BLAKE2b-256 checksum
How to use checksums
7caca64707d03e1d4e55401535461b9248c91e834b19d8233f40e870495dd54d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl

Download URL iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl
Size 1.8 MB
Tags Linux glibc 2.17+ IBM System/390x Python 3
SHA-256 checksum
How to use checksums
c46d6b1c2d372e4940399d1952c0616fbdffc82577bb0b524494051484681507
BLAKE2b-256 checksum
How to use checksums
a573a76a5eee2de4a206f96053e282b6ee7434fab92aa55b729497d76ef8c4e9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl

Download URL iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl
Size 1.7 MB
Tags Linux glibc 2.17+ PowerPC 64-le Python 3
SHA-256 checksum
How to use checksums
4f0da141e49ef4e89f28dec367cc2e65f8bfd55c98bc5da27651127235b30dbd
BLAKE2b-256 checksum
How to use checksums
beb1cdb5fb4ae54918b51360a52d56cbe00a037a9735623aca931014e480f382
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl

Download URL iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Size 1.8 MB
Tags Linux glibc 1.2+ x86-64 Linux glibc 2.17+ x86-64 Python 3
SHA-256 checksum
How to use checksums
f84da7c420a2c7f4601d0f1c2390b09e06d4981e8c40a8e6f990e83de9871c95
BLAKE2b-256 checksum
How to use checksums
b304be83ea9b5340e4f9f14fd8ef8a42ecb4eb99ef05366673c33b734920b510
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl

Download URL iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Size 1.7 MB
Tags Linux glibc 1.2+ ARM64 Linux glibc 2.17+ ARM64 Python 3
SHA-256 checksum
How to use checksums
34173f018b7607817dcdc08d26162d972f4296d1b205478118ce0d44e1bf955d
BLAKE2b-256 checksum
How to use checksums
7dd197c18aaefdcd7a1bb205900e1685d6de02e26c1dda7442f4c34e23837d25
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl

Download URL iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl
Size 1.7 MB
Tags Python 3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
2463c2001f2e2b2bf7acb5104783da7a5dfe2421e78f56a1c1ee47c7aab297de
BLAKE2b-256 checksum
How to use checksums
c6155bed29959f6230003ff8a476a903f273c94e46bb57ee70422d36729af49d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log

Release files / iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl

Download URL iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl
Size 1.9 MB
Tags Python 3 macOS 10.7+ x86-64 macOS 10.9+ x86-64
SHA-256 checksum
How to use checksums
a2f75b362f7b99587cc18e4f38d77371399a27050aa2cc77fd2d62e5d815325a
BLAKE2b-256 checksum
How to use checksums
5865a39b5616f37159e45bb0a022b6f33b1de7c828a2862f0a1bdf9a1c33a8ff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.7

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Jan 25, 2026.

Transparency log
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page