Add-on:The Movie Database Python

From Official Kodi Wiki
Jump to navigation Jump to search

The Movie Database Python

See this add-on on the showcase

Author: Team Kodi
Website: link
Type: Movie information
Repo: repo v21 repo v20 repo v19

License: GPL-2.0-or-later
Source: Source code
Summary: Python TMDB Movie Scraper
Home icon grey.png   ▶ Add-ons ▶ The Movie Database Python
Attention talk.png Need help with this add-on? See here. is a free and open movie database. It's completely user driven by people like you. TMDb is currently used by millions of people every month and with their powerful API, it is also used by many popular media centers like Kodi to retrieve Movie Metadata, Posters and Fanart to enrich the user's experience.


This add-on is installed from the Add-on browser located in Kodi as follows:

  1. Settings
  2. Add-ons
  3. Install from repository
  4. Information providers (v16 and higher)
  5. Movie information
  6. The Movie Database Python
  7. Install


The Movie Database Python scraper is developed and maintained by Team Kodi and is written in Python 3.

The Movie Database Python scraper may access the following sites to scrape your movies and populate your library:


This scraper uses either the filename or the folder name (depending on the setting Movies are in separate folders that match the movie title) as the search string to lookup the title at TheMovieDB site.

If you are experiencing problems scraping the correct title, there are 3 methods available to force the scraper to the correct title.

Scraper Search

If the scraper is unable to find the correct movie, you can perform a search using either the IMDB or TMDB ID's.

  • To search by IMDB ID enter the ttxxxxxx ID directly without any prefix
  • To search by TMDB enter the prefix tmdb/ followed by the ID. eg tmdb/240832.

Filename identifiers

Scrapers can optionally lookup via filename identifiers since Matrix (v21) if the scraper supports it. As of v21, TheMovieDB Python, TMDB TV Shows, and TV Maze scrapers support ID's in the folder or filename.

Filename identifiers are short tags added to the name of a file that directly provide metadata IDs to Kodi. This method streamlines the scraping process by giving Kodi explicit references to look for in its database. If an identifier could not be looked up using a filename identifier, Kodi falls back to the normal scraping process using title and year.

To take advantage of this feature, include the identifier within the filename and/or the folder (depending on the setting Movies are in separate folders that match the movie title in the Set Content screen) using one of the following supported formats:

  • Movie Name (Year) [sourceid=xxxx]
  • Movie Name (Year) [sourceid-xxxx]
  • Movie Name (Year) [source=xxxx]
  • Movie Name (Year) [source-xxxx]
  • Movie Name (Year) {sourceid=xxxx}
  • Movie Name (Year) {sourceid-xxxx}
  • Movie Name (Year) {source=xxxx}
  • Movie Name (Year) {source-xxxx}


sourceid / source - the appropriate site identifier of the ID (see Note below)
xxxx - the ID from the site

An example of a properly formatted filename would be:

/Blade Runner (2017) {tmdb=335984}/Blade Runner (2017) {tmdb=335984}.mkv

Note: Not all scraper sites accept all ID's. It is recommended that the sites own ID is used rather than a 3rd party site (eg imdb). 3rd party ID's at scraper sites rely on users to enter that data. It is not uncommon to have these ID's missing.

TheMovieDB for Movies and TV Shows - Use TMDB's own tmdb ID but the scapers will also accepted imdb and tvdb if that data is available at the site.
TV Maze - only acceptes tvmaze ID's
TVDB - As at the release of v21 Omega, the scraper requires updating by TheTVDB

Parsing NFO File

See: Parsing NFO Files


Scraper settings can be adjusted in three locations, each location having a different result. When adjusting the settings be mindful of where:

1. Kodi System Settings ▶ Add-ons ▶ Information Providers ▶ (Select Scraper)
Scrapers are installed with default settings. Adjusting settings in this location sets the new default settings for your scraper. From this point on any source you change to use this scraper will use the new default settings. Existing sources are not changed
If an existing source is already using this scraper, and you would like the new settings to take effect, change the source to use another scraper, save and answer no to updating the library. Then change the scraper back and the new default settings will be loaded for the source. See: Changing Scrapers
Alternatively, use the next method.
2. Videos ▶ Files ▶ Source ▶ Context Menu ▶ Change Content ▶ Settings
Changing settings at the source will affect that source only.
3. Videos ▶ Files ▶ Source ▶ Movie/TV Show folder ▶ Context Menu ▶ Change Content ▶ Settings
Changing settings on the folder containing a movie or TV show will affect only that movie or TV show.

Note: Changing scraper settings does not change the metadata or artwork already in your library. Only items scraped after the setting changes will be affected.


Image 5- General Settings

Keep Original Title
Use the original (untranslated) title when downloading metadata for a foreign film.
For example the movie Crouching Tiger, Hidden Dragon (2000) is the English translated title of the movie. The Original Name of the movie is 卧虎藏龙. If you prefer the English translated title (or whichever language you have set in the scraper settings), then disable the setting. If you prefer the original title then enable the setting.
Preferred Language
Set which language metadata to scrape
Search Language
If your movie folders and files are named using a language other than English then, to reduce false matches, use this setting to limit the search to the selected language.
Enable posters from TMDb
The scraper uses as first choice for fanart. Enable this setting to download Poster from TMDB instead. Will override the setting.
Enable fanart from TMDb
The scraper uses as first choice for fanart. Enable this setting to download Fanart from TMDB instead. Will override the setting.
Separate TMDb fanart with title to landscape
Fanart is 16:9 artwork with no text. Landscape is fanart with text.
With this setting enabled, 16:9 images with text are scraped as a Landscape image type.
Enable Trailer (YouTube)
Scrapes the links for trailers from YouTube.
If you have locally saved trailers, do not enable this setting. See... Trailers
Preferred Certification Country
Select wich country Content Certification system (MPAA) to use.
Certification Prefix
To display the appropriate Content Advisory Rating flags in your skin, the rating must be prefixed. Check with the skin author what the prefix is for your chosen country. The image shows prefix for Australian Certification.
Default Rating from
Choose which rating to download and display as the default rating. Most skins displays only a single rating. Choices are TMDB, IMDB and Trakt.
Add also IMDB ratings
Download IMDB ratings in addition to the default rating. If IMDB is selected as default above, this setting will not be visible.
Add also ratings
Download ratings in addition to the default rating. If is selected as default above, this setting will not be visible.
Add multiple studios
Scrape all movie studios associated with the movie.
Stop hand.png Enabling this setting will break the display of Studio Icons in your skin. Studio Icons can only be displayed for a single studio.

Add keywords as tags
Scrape Keywords from TMDB and add them as Tags in Kodi
Be aware that larger libraries may be flooded with thousands of tags in Kodi

This section controls artwork scraping from

All artwork related settings are now set in Settings > Media > Videos in the new Artwork section of the Kodi settings. Use these settings to modify which artwork types are downloaded. The default is to download all artwork types.

If you had the artwork tags in your advancedsettings.xml file from v18, these will have been transferred across to the new settings system and added to the Custom setting, otherwise you will need to manually enter which artwork types you prefer.

Image 9-

Enable artwork from
This setting is enabled by default which allows scraping of artwork from
For those that prefer no extended artwork, disable this setting. Artwork will then be limited to Poster, fanart, landscape and clearlogo as provided by TheMovieDB, unless you have further adjusted the artwork settings in Kodi.
Language for artwork
Allows you to select the language of the artwork for poster, clearart, clearlogo, landscape and other types of artwork that contain text. The default setting is English.
Prioritize artworks over preferred language
If an artwork type is not available in your chosen language, then:
Enabling this setting downloads the artwork in the first available language.
Disabling this setting will not download any artwork for that particular artwork type. personal API key(optional)
Enter your personal API key here if you have one.
A personal API key is not required to use these features.
For more information on API keys, see Personal API Key benefits

Return to top