Pythonic interface to fzf

Navigation

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for dahlia from gravatar.com dahlia

Unverified details

These details have not been verified by PyPI
Meta
Classifiers
Report project as malware

Project description

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.

Project details

Verified details

These details have been verified by PyPI
Project links
GitHub Statistics
Maintainers
Avatar for dahlia from gravatar.com dahlia

Unverified details

These details have not been verified by PyPI
Meta
Classifiers

Release history Release notifications | RSS feed

This version

1.9.0.67.0

1.8.0.62.0

1.7.0.62.0

1.6.0.60.3

1.5.0.60.2

1.4.0.60.2

1.4.0.54.3

1.4.0.51.0

1.3.0.51.0

1.2.0.46.1

1.1.0.44.0

1.0.0.42.0

0.5.0.20.0

0.4.0.17.3

0.4.0.17.1

0.3.0.17.1

0.2.0.17.0

0.2.0.16.11

0.2.0.16.10

0.2.0.16.8

0.2.0.16.7

0.1.0.16.7

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

iterfzf-1.9.0.67.0.tar.gz (2.0 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

iterfzf-1.9.0.67.0-py3-none-win_arm64.whl (1.8 MB view details)

Uploaded Python 3Windows ARM64

iterfzf-1.9.0.67.0-py3-none-win_amd64.whl (2.0 MB view details)

Uploaded Python 3Windows x86-64

iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl (1.8 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ s390x

iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (1.7 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ppc64le

iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.8 MB view details)

Uploaded Python 3manylinux: glibc 1.2+ x86-64manylinux: glibc 2.17+ x86-64

iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.7 MB view details)

Uploaded Python 3manylinux: glibc 1.2+ ARM64manylinux: glibc 2.17+ ARM64

iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl (1.7 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl (1.9 MB view details)

Uploaded Python 3macOS 10.7+ x86-64macOS 10.9+ x86-64

File details

Details for the file iterfzf-1.9.0.67.0.tar.gz.

File metadata

  • Download URL: iterfzf-1.9.0.67.0.tar.gz
  • Upload date:
  • Size: 2.0 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for iterfzf-1.9.0.67.0.tar.gz
Algorithm Hash digest
SHA256 9e9ddeba324a6bf7786f6033d1ed5030c2b36bce86ef63f9e76ecb84529e45ac
MD5 942d707ac13742e448cf3bfd5cad3619
BLAKE2b-256 4c5ad955b2ee27ffc7bf48fcb99201e071a39bc68aaa3c3daf4fd4e487b7d21d

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0.tar.gz:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-win_arm64.whl.

File metadata

  • Download URL: iterfzf-1.9.0.67.0-py3-none-win_arm64.whl
  • Upload date:
  • Size: 1.8 MB
  • Tags: Python 3, Windows ARM64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 8ef635f31ae30926a15da944bc8236a31805b7944d06875039998f74b52012cf
MD5 da527747410fb75fd955a7984414dc94
BLAKE2b-256 bf5f4ceb4486a4ab699624be2caa8cdebdfce463ae5906e5511ce52bbcc8621d

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-win_arm64.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-win_amd64.whl.

File metadata

  • Download URL: iterfzf-1.9.0.67.0-py3-none-win_amd64.whl
  • Upload date:
  • Size: 2.0 MB
  • Tags: Python 3, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.7

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 7b4ad3cc6a2e395970be81fb913840ff482b6d9938ecec605e4a6fce9db936fb
MD5 8f2756f5632e38d7e6b291cab1e597f7
BLAKE2b-256 7caca64707d03e1d4e55401535461b9248c91e834b19d8233f40e870495dd54d

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-win_amd64.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl.

File metadata

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl
Algorithm Hash digest
SHA256 c46d6b1c2d372e4940399d1952c0616fbdffc82577bb0b524494051484681507
MD5 49d88a98221e148e1a7b064efdc16f64
BLAKE2b-256 a573a76a5eee2de4a206f96053e282b6ee7434fab92aa55b729497d76ef8c4e9

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl.

File metadata

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl
Algorithm Hash digest
SHA256 4f0da141e49ef4e89f28dec367cc2e65f8bfd55c98bc5da27651127235b30dbd
MD5 9e096cace74117aa1005b6d9b6f09aaa
BLAKE2b-256 beb1cdb5fb4ae54918b51360a52d56cbe00a037a9735623aca931014e480f382

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 f84da7c420a2c7f4601d0f1c2390b09e06d4981e8c40a8e6f990e83de9871c95
MD5 ca15c87dff306736ffa06c58d1f1d238
BLAKE2b-256 b304be83ea9b5340e4f9f14fd8ef8a42ecb4eb99ef05366673c33b734920b510

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 34173f018b7607817dcdc08d26162d972f4296d1b205478118ce0d44e1bf955d
MD5 76cb4e76748dc7ec9a03150c8a75e237
BLAKE2b-256 7dd197c18aaefdcd7a1bb205900e1685d6de02e26c1dda7442f4c34e23837d25

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 2463c2001f2e2b2bf7acb5104783da7a5dfe2421e78f56a1c1ee47c7aab297de
MD5 899e307d002e6cdc33594b2b6edd97db
BLAKE2b-256 c6155bed29959f6230003ff8a476a903f273c94e46bb57ee70422d36729af49d

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-macosx_11_0_arm64.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 a2f75b362f7b99587cc18e4f38d77371399a27050aa2cc77fd2d62e5d815325a
MD5 1670d7392b4fd761ab128cc0391cb5f1
BLAKE2b-256 5865a39b5616f37159e45bb0a022b6f33b1de7c828a2862f0a1bdf9a1c33a8ff

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.9.0.67.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl:

Publisher: release.yaml on dahlia/iterfzf

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page