Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Small module to work with SauceNAO locally

Project description


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


This script runs with Python 3.
There is a currently working Python 2 branch, but I'm not going to update it anymore.
Download this repository and run the to install all necessary dependencies




  • 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

saucenao = SauceNao(directory='directory', databases=999, minimum_similarity=65, combine_api_types=False, api_key='',
                    exclude_categories='', move_to_categories=False,  use_author_as_category=False,
                    output_type=SauceNao.API_HTML_TYPE, start_file='', log_level=logging.ERROR,

or as application:

python --dir [--databases] [--minimum-similarity] [--combine-api-types] [--api-key] [--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 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')).run()

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 compare 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.0.2
Filename, size File type Python version Upload date Hashes
Filename, size SauceNAO-1.0.2-py3-none-any.whl (22.4 kB) File type Wheel Python version py3 Upload date Hashes View hashes
Filename, size SauceNAO-1.0.2.tar.gz (14.9 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page