Skip to main content

Pythonic interface to fzf

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

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


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.8.0.62.0.tar.gz (1.8 MB view details)

Uploaded Source

Built Distributions

iterfzf-1.8.0.62.0-py3-none-win_arm64.whl (1.7 MB view details)

Uploaded Python 3Windows ARM64

iterfzf-1.8.0.62.0-py3-none-win_amd64.whl (1.8 MB view details)

Uploaded Python 3Windows x86-64

iterfzf-1.8.0.62.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl (1.6 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ s390x

iterfzf-1.8.0.62.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl (1.5 MB view details)

Uploaded Python 3manylinux: glibc 2.17+ ppc64le

iterfzf-1.8.0.62.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl (1.6 MB view details)

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

iterfzf-1.8.0.62.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl (1.5 MB view details)

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

iterfzf-1.8.0.62.0-py3-none-macosx_11_0_arm64.whl (1.6 MB view details)

Uploaded Python 3macOS 11.0+ ARM64

iterfzf-1.8.0.62.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl (1.7 MB view details)

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

File details

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

File metadata

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

File hashes

Hashes for iterfzf-1.8.0.62.0.tar.gz
Algorithm Hash digest
SHA256 17f8b787da3561493608ce995f192421ccd5cc6be818fd12db5d3fc54b5aa5eb
MD5 6ee498fbe309e85ac379f09881e5f527
BLAKE2b-256 f63cf1be6cbc6a805dfb1b21d0bdc8b850c3a18f55745acd7f3cf794e1454335

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-win_arm64.whl.

File metadata

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

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-win_arm64.whl
Algorithm Hash digest
SHA256 9ae79840b14c090c6a4590add2eaa90f1e945319433d9c900badf0b588b576f8
MD5 4a205abd74c5a3610c6995d34c807641
BLAKE2b-256 6bb0ff38147ebb94a9ad79781e7356f2b5e69bd79721a9f0653ccf25506c4cfe

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-win_amd64.whl.

File metadata

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

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-win_amd64.whl
Algorithm Hash digest
SHA256 b7cb95f93d5c1d901e8b7ccc886870f48f8331ebbba230cbd49eaedf045f142e
MD5 aaf4bf9a92ed59c68a09d7a9fb4603ad
BLAKE2b-256 5b0f7169c67ba591917c9eb09ab5433cb6c8cc2346baee7b9abab9351da277a6

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl.

File metadata

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-manylinux_2_17_s390x.manylinux2014_s390x.whl
Algorithm Hash digest
SHA256 b43e757b4c0141250aa48cb545083da25e41722d14b003fdc9bddb366a373479
MD5 6865e7636cfdb13276a8fd41da2c41fa
BLAKE2b-256 7b08e9fafe7bc4609f317d50df7cdb3c23a46ec65cedf255bd2ef55916d04e54

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl.

File metadata

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-manylinux_2_17_ppc64le.manylinux2014_ppc64le.whl
Algorithm Hash digest
SHA256 32878d993fc6058641bdec50867a25e199b40736cebb0e28449b8a61b054bf3d
MD5 93db274fef8a93da9bb9c06b2deaa228
BLAKE2b-256 c985520fedf1a01fe014366307ea4b1ce5527e29dfcf042155eb874972dcc1f7

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.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.8.0.62.0-py3-none-manylinux_1_2_x86_64.manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 15094a8ac72d0755d3657333fcd72329ef2d79ea6633c37a6be27be66671ae48
MD5 19f6f628ecb82ca214bbd41dcef99407
BLAKE2b-256 df374349484d7693324e40d51d0dc2f4d52b49b6765598e14af56642075ecdde

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-manylinux_1_2_aarch64.manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 24d5d658995be678a19c8ae633486daa9ef63fd17a2d759581c565885861817c
MD5 1520e16040c8ddd5a30f2c9d31761d29
BLAKE2b-256 67d516d76f04b23ecd4a2e98b112e73b10cfb058a4795a6e63d21df020d1c8cc

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 e18ea2ccf4d572695987d90537977ef060ebf4157e783bb1a72a7f3fa1da2cd0
MD5 987f3bedc3f36f515eef3c12129a85c2
BLAKE2b-256 e52b0c9125d0500df4cec54fcc76a8db86fbffee65fbfdcf85b712231a431829

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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.8.0.62.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl.

File metadata

File hashes

Hashes for iterfzf-1.8.0.62.0-py3-none-macosx_10_7_x86_64.macosx_10_9_x86_64.whl
Algorithm Hash digest
SHA256 057ac19b67128269a2c9efa7d419fef130d0df2210658d0e2fbe5a009b8b09e1
MD5 80fee37f7d5464a8f8853df65a86ac80
BLAKE2b-256 ed07b43cd0d821e39d2d9afc03ca15d658f9c7aed7d8363bb95b2f35c22500bf

See more details on using hashes here.

Provenance

The following attestation bundles were made for iterfzf-1.8.0.62.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 Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page