Kaggle API – The Missing Python Documentation

Official Kaggle API is a command line utility written in Python3, but the documentation only covers command line usage and not Python usage. This post will explain how you can use the API(Version 1.5.6) within Python.

1. Installing Kaggle API

You can run pip install kaggle  to install the api. You might need to run  pip install --user kaggle  on Linux or Mac if you are encountering issues with the installation.

2. Setting up the API Key

Kaggle API requires an API token. Go to the Account Tab ( https://www.kaggle.com/<username>/account ) and click ‘Create API Token’.  A file named kaggle.json will be downloaded. Move this file in to ~/.kaggle/  folder in Mac and Linux or to C:\Users\<username>\.kaggle\  on windows. This is required for authentication and do not skip this step.

Alternatively, you can populate KAGGLE_USERNAME and KAGGLE_KEY  environment variables with values from kaggle.json to get the api to authenticate. Please note that environment variables have precedence over the kaggle.json file and hence setting them incorrectly will result in authentication failure even if you have correct contents in kaggle.json file.

3. Initializing and Authenticating

You can use below lines of code to get an authenticated API instance.

4. Interacting with competitions

4.1 Searching competitions


Most of the list methods in the api have a command line counter part which can be used to display the formatted results. It is not really useful for automation tasks as they dont return anything, but might be useful when exploring the api.




4.2 Listing and downloading competition Files

4.3 Submitting to competitions

4.4 Retrieving Leader Board

5. Interacting with datasets

5.1 Searching datasets

5.2 Listing dataset files

5.3 Downloading Files

6. Interacting with Kernels

6.1 Searching Kernels

6.2 Retrieve a kernels output

6.3 Get the status of the latest kernel run


6.4 Pull a kernel to local machine

6.5 Initialize metadata file for a kernel

6.6 Pushing a kernel to Kaggle


Have any questions? Please add it as comments and I will try my best to answer them.

4 Responses

  1. Amit says:

    This is a wonderful job. Its been of great help in my project.

  2. mz says:

    This help full. I have question, if i have previus version exist how to do like api.dataset_list_files(‘avenn98/world-of-warcraft-demographics/version/1’).files , i want to download some data from previus version. Thanks

  3. Greg says:

    Thanks this is great info. Is there a way to retrieve your score of your most recent competition submission? Retrieving the leaderboard can get you the best score, but not the most recent score.

  1. February 26, 2020

    […] published a blog post that explains most of the common use cases of competition, datasets and kernel […]

Leave a Reply

Your email address will not be published.