These are my notes on building a Kodi Add-on. This is mostly a summarization of the material you can find in the Kodi Wiki Manual.

These notes are focused on the v16.0 Jarvis release.

Add-on Folder Structure

  ├── LICENSE.txt       - Software License (GNU/MIT/GPLv2/Whatever)
  ├──          - Python code for this add-on
  ├── addon.xml         - XML metadata for this add-on
  ├── changelog.txt     - Description of changes per release
  ├── fanart.jpg        - Background image: 16:9 ratio, 1280x720 or 1920x1080
  ├── icon.png          - Icon image: 256x256, solid non-transparent background
  └── resources
    ├── data            - Static data: XLT/XSD, XML, etc
    ├── language        - Translations of the add-on
    ├── lib             - Module definitions, 3rd party libraries
    ├── media           - Pictures, audio, video
    └── settings.xml    - User-configurable settings

Add-on Types and Media Types

  • repository
  • plugin - adds functionality
    • audio
    • video
    • image
    • weather
  • script - a runnable program
    • module - provides support for other add-ons
    • service - runs on login or startup
  • skin
  • resource

The “Hello World” Script


The easiest way to get started is to clone down the HelloWorld repository, open it up in your favorite text editor, and have a look around.

$ git clone
$ atom

Create a symlink to your add-on.

$ # ln -s source destination
$ ln -s ~/code/ ~/Library/Application\ Support/Kodi/addons/

Note: The destination folder will depend on your operating system.

Now, when you make changes to your code, they should be immediately available in the Kodi application.

The userdata Folder and Log File

The userdata folder is where all of your settings and customizations are stored.


Operating System Location
Mac OS X ~/Library/Application Support/Kodi/userdata
Linux ~/.kodi/userdata/
Windows %APPDATA%\kodi\userdata

The docs say that the logfile is located one level up from the userdata folder. I found mine some place slightly different:

$ cd ~
$ find . -name "kodi.log"

Navigate to Settings > System > Logging and enable the following:

  • Enable event logging
    • Enable notification event logging
  • Enable debug logging
  • Enable component-specific event logging

Keep an eye on the logfile while making changes.

$ tail -f ~/Library/Logs/kodi.log


The JSON-RPC Specification allows a client to request a server to run a method/function/procedure (eg- turn up the volume, play a video). Kodi has a built-in JSON-RPC API which allows us to interact with the player, and call “remote procedures” defined by the API.



Get some inspiration by seeing what’s out there. Example Google searches:

  • kodi "plugin.image"
  • kodi ""