Skip to main content

Search and download music album covers

Project description


Smart Automatic Cover Art Downloader

PyPI version AUR version Tests status Coverage Lines of code Supported Python versions License

SACAD is a multi platform command line tool to download album covers without manual intervention, ideal for integration in scripts, audio players, etc.

SACAD also provides a second command line tool, sacad_r, to scan a music library, read metadata from audio tags, and download missing covers automatically, optionally embedding the image into audio audio files.


  • Can target specific image size, and find results for high resolution covers
  • Support JPEG and PNG formats
  • Customizable output: save image along with the audio files / in a different directory named by artist/album / embed cover in audio files...
  • Currently support the following cover sources:
    • Amazon CD (.com, .ca, .cn, .fr, .de, and variants)
    • Amazon digital music
    • CoverLib (site is dead)
    • Deezer
    • Discogs
    • Google Images (removed, too unreliable)
    • Itunes
  • Smart sorting algorithm to select THE best cover for a given query, using several factors: source reliability, image format, image size, image similarity with reference cover, etc.
  • Automatically crunch images with optipng or jpegoptim (can save 30% of filesize without any loss of quality, great for portable players)
  • Cache search results locally for faster future search
  • Do everything to avoid getting blocked by the sources: hide user-agent and automatically take care of rate limiting
  • Automatically convert/resize image if needed
  • Multiplatform (Windows/Mac/Linux)

SACAD is designed to be robust and be executed in batch of thousands of queries:

  • HTML parsing is done without regex but with the LXML library, which is faster, and more robust to page changes
  • When the size of an image reported by a source is not reliable (ie. Google Images), automatically download the first KB of the file to get its real size from the file header
  • Process several queries simultaneously (using asyncio), to speed up processing
  • Automatically reuse TCP connections (HTTP Keep-Alive), for better network performance
  • Automatically retry failed HTTP requests
  • Music library scan supports all common audio formats (MP3, AAC, Vorbis, FLAC..)
  • Cover sources page or API changes are quickly detected, thanks to high test coverage, and SACAD is quickly updated accordingly


SACAD requires Python >= 3.7.

Standalone Windows executable

Windows users can download a standalone binary which does not require Python.

Arch Linux

Arch Linux users can install the sacad AUR package.

From PyPI (with PIP)

  1. If you don't already have it, install pip for Python 3
  2. Install SACAD: pip3 install sacad

From source

  1. If you don't already have it, install setuptools for Python 3
  2. Clone this repository: git clone
  3. Install SACAD: python3 install


Additionally, if you want to benefit from image crunching (lossless recompression to save additional space):

On Ubuntu and other Debian derivatives, you can install both with sudo apt-get install optipng jpegoptim.

Note that depending of the speed of your CPU, crunching may significantly slow down processing as it is very CPU intensive (especially for PNG files).

Command line usage

Two tools are provided: sacad to search and download one cover, and sacad_r to scan a music library and download all missing covers.

Run sacad -h / sacad_r -h to get full command line reference.


To download the cover of Master of Puppets from Metallica, to the file AlbumArt.jpg, targetting ~ 600x600 pixel resolution: sacad "metallica" "master of puppets" 600 AlbumArt.jpg.

To download covers for your library with the same parameters as previous example: sacad_r library_directory 600 AlbumArt.jpg.


  • Only supports front covers

Adding cover sources

Adding a new cover source is very easy if you are a Python developer, you need to inherit the CoverSource class and implement the following methods:

  • getSearchUrl(self, album, artist)
  • parseResults(self, api_data)
  • updateHttpHeaders(self, headers) (optional)

See comments in the code for more information.


Mozilla Public License Version 2.0

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

sacad-2.7.2.tar.gz (40.2 kB view hashes)

Uploaded source

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