From Official Kodi Wiki
< Artwork(Redirected from ThumbnailCache)
Jump to navigation Jump to search
Artwork contents

Artwork Main Page

See also:

Return to:

Home icon grey.png   ▶ Music Library
▶ Video Library
▶ Artwork ▶ Cache


Kodi maintains a texture cache on local device storage for all artwork displayed in the GUI, whether from an online source or the local file system. These textures are optimized and stored locally for faster loading.

When media is added to the library, Kodi initially only has a URL or path to the artwork. The artwork itself is downloaded (if from an online source) and then cached.

All images that Kodi loads, with the exception of textures that are provided directly by the skin, are cached to the userdata/Thumbnails folder.

Note: It is not possible to disable the artwork cache and operate exclusively from locally saved artwork as described in the related artwork pages.

Artwork for library items

The artwork URLs associated with library items are stored in the art table inside the video or music databases. These store the original URL to the artwork (e.g. from local artwork files or from web sources such as,, or This means that central databases store where the art is obtained from, and multiple devices then just keep a local thumbnail cache as described below.

The caching procedure

The caching procedure utilizes an optimized copy of the original image saved in .jpg or .png format and an SQL database that maintains the local cache.

The cache operates primarily on an "as and when needed" basis; i.e. textures are cached when they're first requested for display in a skin or web interface. In some cases textures may be cached before they're immediately needed, such as thumbnails generated from video files. In either case, the main caching procedure starts with an image URL. It caches as follows:

  1. Kodi generates a hash (CRC) of the URL, like "6a643bff".
  2. The texture is optimized (see #Texture optimization) and cached to a device-local file with the given URL hash. It is cached as a PNG if transparency is required and JPG otherwise.
  3. For local files, another hash of the image is generated based on size and modified date, which can be used to check if the original image has changed.
  4. These details are stored in the SQL database Textures.db, along with information on when the image was cached.

Loading textures

When loading a texture for display in a skin or web interface, Kodi basically just has a URL to the image. Given a particular URL, it loads the texture as follows:

  1. If the image is provided by the skin, skip to step 5.
  2. If the URL is directly to a cached version of a texture in the cache, skip to step 5.
  3. If the URL is for an image already cached in the thumbnail cache, swap the URL to the cached version and skip to step 5.
  4. Cache the image as outlined in the section above.
  5. Load the image. If the image is provided by the skin, skip steps 6 and 7.
  6. The access time for this texture is saved in the texture database.
  7. If the image is not from a web service (HTTP/S) and at least 24 hours have passed since it was last loaded, check the hash generated in step 3 of "The caching procedure" for changes to the image. If the hash has changed, cache the new image as outlined in the section above.

Texture optimization

  1. Images are limited to a maximum pixel dimension to fit in a 16:9 box, with a default configuration of 1920x1080 for images that are 16:9 (like fanart) and larger than this, and 1280x720 for all other images. This can be changed with advancedsettings.xml.
    • If you are experiencing slow loading images or lagging GUI navigation on low powered equipment and/or your Kodi device has minimal storage available, these defaults can be lowered to noticeably reduce the cost of artwork. For higher powered equipment these settings can be increased to maintain the original artwork size. (eg 3840x2160 fanart)
  2. Images are re-encoded in a decoder-friendly way so that the image can be displayed as quickly as possible.

This optimized image is exported with Kodi's Library Export feature, rather than the original full-quality image, so it is best to avoid exporting artwork if at all possible.[1]

Advanced: How to refresh the cached image of an icon manually

The Texture Cache Maintenance utility can do this in a safer way, but this is the manual option. There is an image like /home/x/.kodi/addons/my.lovely.addon/icon.png . After changing that file, the old image is still visible in Kodi. To solve this we need to remove the actual thumbnail file from the filesystem and its reference in the DB:

# Get the thumbnail path to remove the file from the filesystem
$ sqlite3 .kodi/userdata/Database/Textures13.db "SELECT cachedurl FROM texture WHERE url = '/home/x/.kodi/addons/my.lovely.addon/icon.png';"

This 6/6a643bff.png is the cached image under /home/x/.kodi/userdata/Thumbnails. So: you need to remove from your filesystem /home/x/.kodi/userdata/Thumbnails/6/6a43bff.png

# Remove the image->cached image link in the DB
$ sqlite3 .kodi/userdata/Database/Textures13.db "DELETE FROM texture WHERE url = '/home/x/.kodi/addons/my.lovely.addon/icon.png';"

Next time Kodi needs the image, it will recreate the thumbnail.

Note: The "Textures13.db" number/version can increase with later Kodi versions.

See also: Database Versions

Advanced: delete textures13.db

This last resort procedure is one sure way to repair any image caching problem: delete the Textures13.db database and the thumbnail directory. This procedure does not affect the entries in the Video and Music libraries, so Kodi will not find more images after, this is just a brute-force solution to a caching problem. It affects the artwork database only. Texture Cache Maintenance utility can do very targeted fixes of the texture cache, so consider it before doing this.


  1. Be aware that this should be a last resort procedure. Deleting this database file and the thumbnail directory will remove all cache entries and links, requiring remote URLs to web services to be downloaded again.
  2. As the URL link to the original artwork location is stored in the video or music databases, Kodi will use the existing URLs to rebuild the Texture database and thumbnail cache, rather than finding new images locally or from a scraper.
  3. Using this procedure, you cannot change the scraping location for artwork. ie- If you originally scraped from online sources, you cannot expect that Kodi will now scrape from your newly added local artwork and vice-versa. It will retrieve artwork from the same source as it was before, so the result will be the same image. To bulk change artwork, refer to Importing-Scraping Artwork

You will need to perform the following for a clean start with respect to the artwork texture cache.

  1. Exit Kodi
  2. Delete texturesxx.db located in the \userdata\database\ folder.
  3. Delete the Thumbnails directory located at \userdata\ which stores all the cached images,

Once the above steps are performed

  1. Restart Kodi
  2. Kodi will automatically rebuild the Textures database and repopulate the Thumbnails cache as the images are displayed in the GUI or other Kodi interface.

Stop hand.png Artwork links must be considered as a perishable item. Scraper sites frequently purge thousands of images. As a result, performing this advanced method may result in many images no longer displaying as they are no longer available at the scraper sites.

Cache manipulation tools

  • Texture Cache Maintenance utility
    • Texture Cache Maintenance utility is a python script created by MillhouseVH, that can do a number of artwork related maintenance on the Kodi library. The script can be used to pre-generate thumbnails, clean up old thumbnail files, find corrupted files, and much more. The script can work on any OS that can run Python 2.6 or higher.

Kodi version updates

From v18, the 1920x1080 resolution limitation has been removed. Using the following code in your advancedsettings.xml will allow caching artwork at original size. [2]



Return to top