Skip to main content

Small module to work with SauceNAO locally

Project description


tests Coverage Status GitHub Scrutinizer Code Quality
unofficial python module to make working with SauceNAO in projects easier


This package requires Python 3.6 or later.

You can simply install the latest version with

pip install SauceNAO

Alternatively you can download this repository and run the to install all necessary dependencies. In case you want to install the dependencies to run the unit tests you can additionally run pip install -e .[dev] in this project.




  • Pillow - Python Imaging Library, used to generate images for unittests
  • python-dotenv - .env file loader used for unittests
  • requests-mock - requests mock responses used for unittests


You can run SauceNAO either as module:

import logging

from saucenao import SauceNao, SauceNaoDatabase

saucenao = SauceNao(directory='directory', databases=SauceNaoDatabase.All, minimum_similarity=65,
                    combine_api_types=False, api_key='', is_premium=False, exclude_categories='',
                    move_to_categories=False, use_author_as_category=False, output_type=SauceNao.API_HTML_TYPE,
                    start_file='', log_level=logging.ERROR, title_minimum_similarity=90)

or as application:

python --dir [--databases] [--minimum-similarity] [--combine-api-types] [--api-key] [--premium]
                [--exclude-categories] [--move-to-categories] [--use-author-as-category] [--output-type] [--start-file]
                [--log-level] [--filter-creation-date] [--filter-modified-date] [--title-minimum-similarity]

you can also use it to get the gathered information for your own script:

filtered_results = saucenao.check_file(file_name='test.jpg')
# or with streams/byte objects
filtered_results = saucenao.check_file(io.BytesIO(b'\x00'))

or get a generator object for a bulk of files using the worker class, all parameters work here too:

from saucenao import Worker

results = Worker(directory='directory', files=('test.jpg', 'test2.jpg', io.BytesIO(b'\x00'))).run()

the worker automatically differentiates between file names and BinaryIO objects, so you can simply pass both types at the same time.

Running the tests

In the tests folder you can run each unittest individually.
The test cases should be self-explanatory.


Want to contribute? Great!
I'm always glad hearing about bugs or pull requests.


This project is licensed under the MIT License - see the file for details


A big thanks to SauceNAO who are indexing all the images and compares them.
This script would be completely useless without them.

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 SauceNAO, version 1.1.0
Filename, size File type Python version Upload date Hashes
Filename, size SauceNAO-1.1.0-py3-none-any.whl (25.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size SauceNAO-1.1.0.tar.gz (16.5 kB) File type Source Python version None Upload date Hashes View

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 Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page