Kaggle CLI

Warnings

• gotcha Authentication failures are the most common issue. Ensure your Kaggle API credentials (`kaggle.json`) are correctly placed in `~/.kaggle/` or that `KAGGLE_USERNAME` and `KAGGLE_KEY` environment variables are properly set. The library automatically looks for these locations/variables.
  Fix: Refer to the official Kaggle API documentation for detailed authentication steps. Generate a new API token from your Kaggle account settings and place the `kaggle.json` file in `~/.kaggle/` (on Linux/macOS) or `C:\Users\<Windows-username>\.kaggle\` (on Windows). Alternatively, set `KAGGLE_USERNAME` and `KAGGLE_KEY` as environment variables.
• gotcha Kaggle enforces dynamic rate limits on API calls. Excessive or rapid requests can lead to HTTP 429 ('Too Many Requests') errors. This is particularly relevant for automated scripts.
  Fix: Implement pauses or retry mechanisms with exponential backoff in your code to handle rate limiting. Review your logic to ensure no unintended loops or redundant calls are being made.
• gotcha The library's behavior, especially regarding authentication and resource caching, can differ when run inside a Kaggle Notebook environment compared to a local machine. For instance, `kagglehub` (a related library) is authenticated by default in Kaggle notebooks, but the `kaggle` CLI requires explicit local setup.
  Fix: Always ensure your local environment is correctly configured for authentication as described above. Be aware that file paths and permissions may also behave differently within Kaggle's sandboxed environments.
• breaking The `kaggle` library (Kaggle CLI) now requires Python 3.11 or newer. Older Python versions (e.g., 3.10 and below) are not supported and will lead to installation or runtime errors.
  Fix: Upgrade your Python environment to version 3.11 or higher. Using a virtual environment is recommended to manage Python versions for different projects.

Install

• pip install kaggle Install `kaggle` library

Imports

• KaggleApi

  from kaggle.api.kaggle_api_extended import KaggleApi

  While `import kaggle` is valid, it does not directly expose the API client. The programmatic API is typically accessed via `KaggleApi` from the `kaggle.api.kaggle_api_extended` submodule.

Quickstart

This quickstart demonstrates how to initialize the Kaggle API client and perform a basic operation, such as listing recently created competitions. It also includes commented-out code for downloading a dataset. Ensure you have set up your Kaggle API credentials either by placing `kaggle.json` in `~/.kaggle/` or by setting the `KAGGLE_USERNAME` and `KAGGLE_KEY` environment variables.

import os
from kaggle.api.kaggle_api_extended import KaggleApi

# --- Authentication --- 
# Option 1 (Recommended for local dev): Place kaggle.json in ~/.kaggle/
#   (Download from Kaggle profile settings: Account -> 'Create New API Token')
# Option 2: Set environment variables (e.g., in your shell or .env file)
#   export KAGGLE_USERNAME='your_username'
#   export KAGGLE_KEY='your_api_key'

# Initialize the API client
api = KaggleApi()
api.authenticate() # This will automatically load credentials

# --- Example: List competitions ---
print('Listing recent competitions:')
# Use 'recentlyCreated' for newer competitions, or 'recentlyUpdated' etc.
competitions = api.competitions_list(sort_by='recentlyCreated', page_size=5)
for comp in competitions:
    print(f"- {comp.title} (ID: {comp.id})")

# --- Example: Download a public dataset ---
# Replace 'dataset-owner/dataset-name' with the actual dataset reference.
# For example: 'lakshmi25npathi/sentiment-analysis-on-movie-reviews'
# Make sure you have permission to download the dataset (some require acceptance of rules).
# try:
#     print(f"\nDownloading dataset...")
#     api.dataset_download_files(
#         'lakshmi25npathi/sentiment-analysis-on-movie-reviews', 
#         path='./data', 
#         unzip=True
#     )
#     print("Dataset downloaded to ./data and unzipped.")
# except Exception as e:
#     print(f"Error downloading dataset: {e}")