Skip to main content

A tool for finding files in the filesystem

Project description



ff is a tool for finding files in the filesystem.

NOTE: ff is in the early stages of development, expect things to break and syntax to change.


ff is a tool for finding files in the filesystem that all share a set of common features. Its scope is similar to find(1) and fd(1) but it aims at being more accessible and easier to use than find and more versatile and powerful than fd. It is written in Python >= 3.6.


  • Search by file attributes.
  • Search in a wide variety of file metadata.
  • Simple yet powerful expression syntax.
  • Flexible output options.
  • Flexible sort options.
  • Extendable by user plugins.
  • Parallel search and processing.
  • Usable in scripts with a Python API.


Store all files from the current directory that are tracked by git(1) in a tar(1) archive:

$ ff type=f git.tracked=yes --sort --exec-batch tar cvzf git-tracked.tar.gz

Find files in the directory Videos/ that end with .mkv or .mp4 and are between 720 and 1080 pixels high:

$ ff Videos/ {{ ext=mkv or ext=mp4 }} and {{ height+=720 and height-=1080 }}

More examples are here.


To build and install ff simply type:

$ python install


$ pip install find-ff

Building with Cython is also supported. Cython >= 3.0 is required. Depending on the set of arguments this may offer a significant speed-up.

$ python install

Python API

You can use ff's query capabilities in your own scripts:

from ff import Find

for entry in Find("type=f git.tracked=yes", directories=["/home/user/project"], sort=["path"]):

Developing plugins and debug mode

There is a template for new plugins to start from ( with exhaustive instructions and comments, so you can develop plugins for your own needs.

Useful in that regard is ff's debug mode. It can be activated by executing the ff module.

$ python -m ff --debug info,cache ...

Debug mode produces lots of messages which can be limited to certain categories using the --debug category1,category2,... option. On top of that, debug mode activates many internal checks using assert(). Therefore, it is advisable to use debug mode during plugin development.

Project details

Download files

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

Files for find-ff, version 601
Filename, size File type Python version Upload date Hashes
Filename, size find_ff-601-py3-none-any.whl (120.8 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size find-ff-601.tar.gz (88.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page