{"id":5982,"library":"kaggle","title":"Kaggle CLI","description":"The `kaggle` Python library, also known as Kaggle CLI, provides a command-line interface and a Python API to interact with Kaggle resources such as competitions, datasets, models, and notebooks. It enables programmatic listing, downloading, creating, updating, and deleting of these resources. The current version is 2.0.1, with releases happening periodically based on feature additions and bug fixes, ensuring access to the latest Kaggle platform features.","status":"active","version":"2.0.1","language":"en","source_language":"en","source_url":"https://github.com/Kaggle/kaggle-cli","tags":["data science","machine learning","api client","kaggle","cli"],"install":[{"cmd":"pip install kaggle","lang":"bash","label":"Install `kaggle` library"}],"dependencies":[{"reason":"Requires Python 3.11 or newer for compatibility.","package":"python","optional":false}],"imports":[{"note":"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.","wrong":"import kaggle","symbol":"KaggleApi","correct":"from kaggle.api.kaggle_api_extended import KaggleApi"}],"quickstart":{"code":"import os\nfrom kaggle.api.kaggle_api_extended import KaggleApi\n\n# --- Authentication --- \n# Option 1 (Recommended for local dev): Place kaggle.json in ~/.kaggle/\n#   (Download from Kaggle profile settings: Account -> 'Create New API Token')\n# Option 2: Set environment variables (e.g., in your shell or .env file)\n#   export KAGGLE_USERNAME='your_username'\n#   export KAGGLE_KEY='your_api_key'\n\n# Initialize the API client\napi = KaggleApi()\napi.authenticate() # This will automatically load credentials\n\n# --- Example: List competitions ---\nprint('Listing recent competitions:')\n# Use 'recentlyCreated' for newer competitions, or 'recentlyUpdated' etc.\ncompetitions = api.competitions_list(sort_by='recentlyCreated', page_size=5)\nfor comp in competitions:\n    print(f\"- {comp.title} (ID: {comp.id})\")\n\n# --- Example: Download a public dataset ---\n# Replace 'dataset-owner/dataset-name' with the actual dataset reference.\n# For example: 'lakshmi25npathi/sentiment-analysis-on-movie-reviews'\n# Make sure you have permission to download the dataset (some require acceptance of rules).\n# try:\n#     print(f\"\\nDownloading dataset...\")\n#     api.dataset_download_files(\n#         'lakshmi25npathi/sentiment-analysis-on-movie-reviews', \n#         path='./data', \n#         unzip=True\n#     )\n#     print(\"Dataset downloaded to ./data and unzipped.\")\n# except Exception as e:\n#     print(f\"Error downloading dataset: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Upgrade your Python environment to version 3.11 or higher. Using a virtual environment is recommended to manage Python versions for different projects.","message":"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.","severity":"breaking","affected_versions":"2.0.0 and later"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}