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.

Source Distribution

SauceNAO-1.1.0.tar.gz (16.5 kB view hashes)

Uploaded source

Built Distribution

SauceNAO-1.1.0-py3-none-any.whl (25.3 kB view hashes)

Uploaded py3

Supported by

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