Skip to main content

Search, filter, inspect, download posts from Danbooru and local folders.

Project description


PyPI downloads PyPI version PyPI pyversions

Search, filter, inspect, download posts from Danbooru/Safebooru and find them back from the command line without setting up any service or database.

Suitable for daily terminal usage, usable for scripts and as a library for Python 3.6+.

See also lunasync to automatically download and keep in sync particular tags using lunafind, similar to Danbooru tag subscriptions or saved searches.


  • Operate on tag searches, URLs or file paths
  • Combine results from multiple searches
  • Specify custom page ranges, or just get everything
  • Filter and order booru results to work around the two tags search limit
  • Optional partial/fuzzy tag matching for filter and local searches
  • Search downloaded posts by tags as if they were on a booru, without the hassle of setting up one
  • Instant results from local searches in most cases after indexing
  • Fast multithreaded downloads; 8 downloads in parallel by default
  • Supports operating on post media (image, ugoira WebM, etc), info, notes, artist commentaries:
    • Getting the URLs or file/folder paths
    • Printing on standard output
    • Downloading

Local searches performance

The first time a local post search is done, an index file to speed up future searches will be automatically created and updated when new post directories exist or are removed.

Test with ~165 000 posts
AMD FX-8300 (8 cores, 3.3GHz), TOSHIBA DT01ACA2 7200 RPM HDD, BTRFS file system, Void Linux 4.18.14 x86_64:

  • It takes about 2m30s - 3m to index everything from scratch
  • After this, search results start coming instantly unless --random or --order is used.
  • Searches finish completely in 8-20s

Test with ~60 000 posts
Celeron B815 (2 cores, 1.60GHz), 5400 RPM HDD, BTRFS file system, Void Linux 4.18.20 x86_64:

  • About 4mn to index everything from scratch
  • Results come instantly
  • Searches finishes in ~20s

Command line usage

Downloading to the current folder every post tagged blonde and 2girls (default booru is

    lunafind "blonde 2girls" --limit 200 --pages all --download .

Searching through the posts we just downloaded, printing image paths for the results:

    lunafind "blonde blue_eyes rating:s score:>5" --source . --show-location media

See lunafind --help for all options and examples.

Python usage

No real documentation yet. Three main classes are provided:

  • Post: represents a local or remote single post, with its info, media, notes and artcom (artist commentary).

  • Album: works like a dictionary of Post, where keys are the post IDs. Has magic methods and operators to facilitate working with them. Can be filtered, ordered, downloaded, and more.

  • Stream: an efficiant lazy iterator yielding posts. Can be filtered and multithread-downloaded.

Reproducing the command line examples in the section above:

    from lunafind import Stream

    Stream("blonde 2girls", limit=200, pages="all").download()

    for post in Stream("blonde blue_eyes rating:s score:>5", client="."):


Requires Python 3.6+ and pip (for automatic easy install).
Tested on GNU/Linux and Windows 7, probably works on OSX and other POSIX systems.
As root:

    pip3 install -U lunafind

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

lunafind-0.5.5.tar.gz (28.4 kB view hashes)

Uploaded source

Built Distribution

lunafind-0.5.5-py3-none-any.whl (48.8 kB view hashes)

Uploaded py3

Supported by

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