Kaggle API CLI

Kaggle API / CLI / kagglehub

Scope

Use for Kaggle official programmatic access:

• kaggle CLI: competitions, datasets, kernels/notebooks, models, config.
• kagglehub Python library: download/load/upload datasets, models, competitions, notebook outputs.
• Kaggle Public API OAuth 2.0 provider: access tokens, refresh tokens, scopes.

Official sources read:

• https://www.kaggle.com/docs/api
• https://github.com/Kaggle/kaggle-api/blob/main/docs/README.md
• https://github.com/Kaggle/kaggle-api/tree/main/docs
• https://github.com/Kaggle/kagglehub/blob/main/README.md

First Checks

command -v kaggle
kaggle --version
kaggle --help
python3 - <<'PY'
import importlib.util
print('kagglehub', bool(importlib.util.find_spec('kagglehub')))
PY

Important pitfall: Kaggle docs on GitHub main may be ahead of the PyPI CLI currently installed. If docs mention kaggle auth, forums, or benchmarks but kaggle --help does not show them, trust the live CLI for execution and use docs as forward reference.

Install

Prefer isolated install on user machines:

python3 -m pip install --user kaggle
# or, if pipx is healthy:
pipx install kaggle

If pipx fails because its shared venv points at a broken Python, use a dedicated venv:

python3 -m venv ~/.local/venvs/kaggle-cli
~/.local/venvs/kaggle-cli/bin/python -m pip install -U pip kaggle
mkdir -p ~/.local/bin
ln -sf ~/.local/venvs/kaggle-cli/bin/kaggle ~/.local/bin/kaggle

For Python workflows:

python3 -m pip install kagglehub

Authentication

Official docs list these auth methods:

1. OAuth CLI login: kaggle auth login if supported by the installed CLI.
2. API token env var: export KAGGLE_API_TOKEN=*** if supported.
3. API token file: ~/.kaggle/access_token if supported.
4. Legacy credentials: ~/.kaggle/kaggle.json with JSON keys username and key.

Most reliable legacy setup:

mkdir -p ~/.kaggle
chmod 700 ~/.kaggle
# write ~/.kaggle/kaggle.json as: {"username":"...","key":"..."}
chmod 600 ~/.kaggle/kaggle.json

Verify without leaking secrets:

stat -f '%A %N' ~/.kaggle/kaggle.json 2>/dev/null || stat -c '%a %n' ~/.kaggle/kaggle.json
kaggle config view 2>&1 | sed -E 's/(key|token|password).*/\1: ***/Ig'

If kaggle datasets download raises KeyError: 'username', the legacy JSON is missing username or the installed CLI does not understand the token-only auth method.

Dataset Commands

Find/list:

kaggle datasets list -s iris
kaggle datasets list --file-type csv --sort-by updated --page 2
kaggle datasets files owner/dataset-slug

Download:

kaggle datasets download owner/dataset-slug
kaggle datasets download owner/dataset-slug --unzip -p ./data
kaggle datasets download owner/dataset-slug -f file.csv -p ./data -o

Flags: -p/--path, --unzip, -f/--file-name, -o/--force, -q/--quiet, -w/--wp.

Create/update:

kaggle datasets init -p ./dataset
# edit dataset-metadata.json: title, id/slug, licenses
kaggle datasets create -p ./dataset --public
kaggle datasets version -p ./dataset -m "update notes"
kaggle datasets metadata owner/dataset-slug -p ./dataset
kaggle datasets status owner/dataset-slug

Use delete only when explicitly requested:

kaggle datasets delete owner/dataset-slug --yes

Competition Commands

kaggle competitions list --group general --category featured
kaggle competitions files titanic
kaggle competitions download titanic -p ./titanic
kaggle competitions submit titanic -f submission.csv -m "message"
kaggle competitions submissions titanic
kaggle competitions leaderboard titanic -d -p ./leaderboard

Code competition submit form:

kaggle competitions submit <competition> -k <username>/<kernel-slug> -f <output-file> -v <kernel-version> -m "message"

Kernels / Notebooks

kaggle kernels list -s search-term
kaggle kernels files owner/kernel-slug
kaggle kernels init -p ./kernel
kaggle kernels pull owner/kernel-slug -p ./kernel -m
kaggle kernels push -p ./kernel
kaggle kernels output owner/kernel-slug -p ./output
kaggle kernels status owner/kernel-slug

Delete requires explicit user intent:

kaggle kernels delete owner/kernel-slug --yes

Models

Current/legacy CLI commonly uses models instances rather than docs models variations:

kaggle models list -s gemini
kaggle models init -p ./model
kaggle models create -p ./model
kaggle models get owner/model-slug -p ./model
kaggle models update -p ./model
kaggle models instances files owner/model/framework/variation
kaggle models instances versions download owner/model/framework/variation/1 -p ./model --untar

Check kaggle models --help before using docs examples.

kagglehub Python

Download dataset:

import kagglehub
path = kagglehub.dataset_download('owner/dataset-slug')
print(path)

Load dataset directly:

import kagglehub
from kagglehub import KaggleDatasetAdapter

df = kagglehub.load_dataset(
    KaggleDatasetAdapter.PANDAS,
    'owner/dataset-slug',
    'file.csv',
)

Supported adapters in docs: PANDAS, HUGGING_FACE, POLARS. It can also download models, competitions, notebook outputs, install utility scripts, and upload datasets/models.

Cache defaults to a local Kaggle cache outside Kaggle notebooks. Change it with:

export KAGGLEHUB_CACHE=./.kagglehub-cache

OAuth 2.0 Public API

Kaggle supports Authorization Code with PKCE.

Discovery:

python3 - <<'PY'
import urllib.request
for u in [
 'https://www.kaggle.com/.well-known/oauth-authorization-server',
 'https://www.kaggle.com/.well-known/oauth-protected-resource',
]:
 print(u)
 print(urllib.request.urlopen(u, timeout=20).read().decode()[:1000])
PY

Endpoints:

• authorize: GET https://www.kaggle.com/api/v1/oauth2/authorize
• token: POST https://www.kaggle.com/api/v1/oauth2/token
• introspect: POST https://www.kaggle.com/api/v1/oauth2/introspect

Public clients require PKCE code_verifier / code_challenge and no auth header. Organization clients use client id org:<slug>, HTTP Basic auth with org owner's Kaggle API key, HTTPS redirect URIs, and no PKCE.

Tokens:

• access token prefix: KGAT_...
• refresh token prefix: KGRT_...
• access token expiry: 3 hours
• use Authorization: Bearer KGAT_... for API calls

Security rules:

• validate OAuth state
• request minimal scopes
• store refresh tokens securely
• never expose organization owner's API key client-side

Common scopes:

• datasets.get:*, datasets.update:*
• models.get:*, models.create:*, models.update:*
• kernels.get:*, kernels.update:*
• competitions.get:*, competitions.submit:*
• role scopes: datasets.viewer:*, datasets.editor:*, models.viewer:*, kernels.editor:*, resources.viewer:*

Rate Limits

Kaggle uses dynamic rate limiting for both website and public API calls. On HTTP 429 / Too many requests:

1. pause and retry after minutes, preferably with exponential backoff;
2. inspect loops/retries for accidental request storms;
3. reduce pagination and redundant polling;
4. report platform-side bugs only after local logic is ruled out.

Safe Defaults

• Do not print KGAT_, KGRT_, KAGGLE_API_TOKEN, or key values.
• Redact credentials in logs with sed -E 's/(KGAT_|KGRT_)[A-Za-z0-9_\-]+/\1***/g'.
• Confirm before destructive operations: dataset/model/kernel/version delete, competition submit, benchmark push/run if it spends quota.
• Prefer --unzip -p <dir> for dataset downloads to avoid dumping files into cwd.
• Always verify artifact paths after download:

find ./data -maxdepth 2 -type f | sort | head -50