Kaggle CLI 完整教學

從安裝認證到競賽提交、資料集管理、模型上傳與 LLM 基準測試：Kaggle 官方 CLI 的全方位操作指南。

1. 專案定位

這是什麼？

Kaggle CLI 是 Kaggle 官方維護的 Python command-line interface（命令列介面），讓你在終端機中完成 Kaggle 平台上的所有操作：下載競賽資料、提交預測、管理資料集、執行 notebook、上傳模型、瀏覽論壇、甚至跑 LLM benchmark（基準測試）。

核心數據

指標	數值
GitHub Stars	7,357
Forks	1,363
License	Apache-2.0
最新版本	v2.2.1 (2026-06-03)
主要語言	Python
最低 Python 版本	3.11+
PyPI 套件名	`kaggle`

10 大命令群組

 1kaggle
 2├── competitions (c)  — 競賽：列表/下載/提交/排行榜/團隊提交
 3├── datasets (d)      — 資料集：搜尋/下載/建立/更新/刪除
 4├── kernels (k)       — Notebook/Script：列表/推送/拉取/執行/輸出
 5├── models (m)        — 模型：列表/建立/更新/刪除
 6├── files             — 檔案管理
 7├── forums (f)        — 論壇：瀏覽/閱讀討論
 8├── benchmarks (b)    — LLM 基準測試：定義/執行/下載結果
 9├── config            — 設定：查看/設定/清除
10├── auth              — 認證：OAuth 登入
11└── quota             — 配額：GPU/TPU 加速器使用量

2. 安裝指南

安裝

1pip install kaggle

若遇到 Command kaggle not found，確認 Python scripts 目錄在 $PATH 中：

Linux：~/.local/bin
Windows：$PYTHON_HOME/Scripts

認證設定（4 種方式）

方式 A：OAuth（推薦）

1kaggle auth login

會開啟瀏覽器完成認證，自動儲存 token。

方式 B：環境變數

1export KAGGLE_API_TOKEN=xxxxxxxxxxxxxx

Token 從 Kaggle Settings > API 取得。

方式 C：Token 檔案

將 API token 存到 ~/.kaggle/access_token。

方式 D：Legacy API Credentials

從 Kaggle 帳號下載 kaggle.json，放到 ~/.kaggle/kaggle.json：

1{"username":"YOUR_USERNAME","key":"YOUR_API_KEY"}

驗證安裝

1kaggle --version
2kaggle --help

3. 核心架構解析

3.1 CLI 架構總覽


flowchart TD
    User["使用者"] -->|kaggle 指令| CLI["cli.py
argparse 路由
10 個 subparser"]
    CLI --> API["kaggle_api_extended.py
8,012 行核心 API
所有 HTTP 請求邏輯"]
    API --> SDK["kagglesdk
Python SDK
gRPC / REST"]
    SDK --> Server["api.kaggle.com
Kaggle API Server"]
    
    CLI --> Auth["認證層"]
    Auth --> OAuth["OAuth
瀏覽器登入"]
    Auth --> Token["API Token
~/.kaggle/access_token"]
    Auth --> Legacy["Legacy Key
~/.kaggle/kaggle.json"]
    Auth --> Env["環境變數
KAGGLE_API_TOKEN"]

3.2 命令群組對應關係


flowchart LR
    subgraph Data ["資料操作"]
        C["competitions
競賽"]
        D["datasets
資料集"]
        F["files
檔案"]
    end
    
    subgraph Compute ["運算操作"]
        K["kernels
Notebook"]
        M["models
模型"]
        B["benchmarks
LLM 測試"]
    end
    
    subgraph Community ["社群"]
        FO["forums
論壇"]
    end
    
    subgraph System ["系統"]
        CF["config
設定"]
        AU["auth
認證"]
        Q["quota
配額"]
    end

3.3 技術棧

層級	技術
CLI Framework	argparse（Python 內建）
HTTP Client	requests
API SDK	kagglesdk（gRPC / REST）
Build System	hatch / hatchling
Linting	black + mypy
Testing	pytest
Packaging	PyPI (`kaggle`)

4. 核心功能詳解

4.1 Competitions（競賽）

 1# 列出競賽
 2kaggle competitions list
 3kaggle competitions list --category featured --sort-by prize
 4
 5# 下載競賽資料
 6kaggle competitions download -c titanic
 7kaggle competitions download -c titanic -f train.csv  # 單一檔案
 8
 9# 提交預測
10kaggle competitions submit -c titanic -f submission.csv -m "my first submission"
11
12# 查看提交記錄
13kaggle competitions submissions -c titanic
14
15# 查看排行榜
16kaggle competitions leaderboard -c titanic --show
17
18# 團隊提交（v2.2.1 新增）
19kaggle competitions team-submissions -c titanic

4.2 Datasets（資料集）

 1# 搜尋資料集
 2kaggle datasets list -s "covid"
 3kaggle datasets list --sort-by votes --file-type csv
 4
 5# 下載資料集
 6kaggle datasets download -d username/dataset-slug
 7
 8# 建立新資料集
 9mkdir my-dataset && cd my-dataset
10echo "id,value" > data.csv
11kaggle datasets init          # 產生 metadata
12kaggle datasets create -p .   # 上傳
13
14# 更新資料集
15kaggle datasets version -p . -m "Added new columns"
16
17# 查看資料集狀態
18kaggle datasets status username/dataset-slug

4.3 Kernels / Notebooks

 1# 列出 notebook
 2kaggle kernels list --mine
 3kaggle kernels list -s "image classification" --language python
 4
 5# 拉取 notebook
 6kaggle kernels pull username/kernel-slug -p ./local-dir
 7
 8# 推送 notebook
 9kaggle kernels push -p ./local-dir
10
11# 查看輸出
12kaggle kernels output username/kernel-slug
13
14# 查看執行狀態
15kaggle kernels status username/kernel-slug

4.4 Models（模型）

 1# 列出模型
 2kaggle models list --owner google --sort-by downloadCount
 3
 4# 查看模型詳情
 5kaggle models get owner/model-slug
 6
 7# 建立模型
 8kaggle models init -p ./model-dir
 9kaggle models create -p ./model-dir
10
11# 建立 variation + version
12kaggle model-variations create -p ./variation-dir
13kaggle model-variation-versions create -p ./version-dir

4.5 Forums（論壇）

1# 列出論壇
2kaggle forums
3
4# 列出論壇主題
5kaggle forums topics -f <forum_id>
6
7# 閱讀討論串
8kaggle forums topic -t <topic_id>

4.6 Benchmarks（LLM 基準測試）— v2.2+ 新增

 1# 初始化 benchmark 環境
 2kaggle benchmarks init
 3
 4# 列出任務
 5kaggle benchmarks tasks list
 6
 7# 執行 benchmark
 8kaggle benchmarks run -t <task_id> -m <model_name>
 9
10# 查看結果
11kaggle benchmarks results -t <task_id>
12
13# 下載結果
14kaggle benchmarks download -t <task_id>

4.7 Config（設定）

 1# 查看設定
 2kaggle config view
 3
 4# 設定預設競賽
 5kaggle config set -n competition -v titanic
 6
 7# 設定下載路徑
 8kaggle config set -n path -v ~/kaggle-data
 9
10# 設定代理
11kaggle config set -n proxy -v http://proxy:8080
12
13# 清除設定
14kaggle config unset -n competition

4.8 Quota（配額）

1# 查看 GPU/TPU 配額
2kaggle quota

5. 應用場景

場景 A：競賽工作流

完整的 Kaggle 競賽 CLI 工作流：

 1# 1. 找到感興趣的競賽
 2kaggle competitions list --category featured
 3
 4# 2. 下載資料
 5kaggle competitions download -c titanic
 6
 7# 3. 本地訓練模型（你的程式碼）
 8python train.py
 9
10# 4. 提交預測
11kaggle competitions submit -c titanic -f submission.csv -m "XGBoost v2"
12
13# 5. 查看排名
14kaggle competitions leaderboard -c titanic --show

場景 B：自動化資料管線

用 cron / CI 自動更新資料集：

1# 每日更新資料集
2python collect_data.py
3kaggle datasets version -p ./data-dir -m "Daily update $(date +%Y-%m-%d)"

場景 C：模型版本管理

1# 訓練完成後上傳模型
2kaggle model-variation-versions create -p ./model-output \
3  --version-notes "Fine-tuned with new data, accuracy 95.2%"

場景 D：LLM 評估

使用 benchmarks 功能評估不同 LLM 在特定任務上的表現：

1kaggle benchmarks init
2kaggle benchmarks run -t summarization -m gpt-4o
3kaggle benchmarks run -t summarization -m claude-3.5-sonnet
4kaggle benchmarks results -t summarization

場景 E：AI Agent 整合

Kaggle CLI 內建 Agent Skill（skills/SKILL.md），可被 Claude Code / Codex 等 AI agent 自動發現，讓 agent 直接操作 Kaggle 資源。

6. 資安掃描報告

掃描範圍

項目	結果
硬編碼機密	❌ 無（所有 credential 走認證流程）
危險函式呼叫	❌ 無（不使用 eval/exec/subprocess with shell=True）
Token 處理	✅ OAuth token + API key 存在本地安全路徑
網路請求	⚠️ 所有操作需連 api.kaggle.com
檔案權限	✅ v2.2.1 新增 auth file 權限設定（chmod 600）
依賴供應鏈	⚠️ 依賴 kagglesdk / requests / protobuf 等

掃描結論

🟢 低風險 — Kaggle 官方維護的工具，Apache-2.0 license。所有認證 token 走標準認證流程（OAuth / API key file），v2.2.1 新增了 auth file 權限保護。程式碼中的 token 字樣都是 API pagination token 或上傳 token，非硬編碼機密。唯一需注意：

~/.kaggle/kaggle.json（Legacy API key）應設定 chmod 600
在 CI 環境中使用環境變數而非檔案存放 credential

7. FAQ

Q1：kaggle 和 kagglehub 有什麼不同？

A： kaggle（本工具）是全功能 CLI，覆蓋 competitions / datasets / kernels / models 等所有操作。kagglehub 是更輕量的 Python library，專注於資料集和模型的下載，適合在 notebook 或 script 中直接呼叫。

Q2：v2.x 和 v1.x 有什麼差異？

A： v2.0 重寫了底層，改用 kagglesdk 取代舊的 kaggle_api。舊的 kaggle_api.py 已被標記為 deprecated。v2.2+ 新增了 forums、benchmarks 等新功能。

Q3：可以在 Docker 中使用嗎？

A：可以。Repo 內含 Dockerfile 和 docker-hatch 腳本，可在一致的環境中執行。也可以自己寫 Dockerfile：

1FROM python:3.11
2RUN pip install kaggle

Q4：如何在 CI/CD 中使用？

A：設定 KAGGLE_API_TOKEN 環境變數（或 KAGGLE_USERNAME + KAGGLE_KEY），CI 會自動認證：

1env:
2  KAGGLE_API_TOKEN: ${{ secrets.KAGGLE_API_TOKEN }}
3steps:
4  - run: pip install kaggle
5  - run: kaggle competitions download -c titanic

Q5：下載很慢怎麼辦？

A：可以設定 proxy：

1kaggle config set -n proxy -v http://your-proxy:8080

或使用 -f 參數只下載特定檔案，避免下載整個競賽資料。

8. 進階技巧

8.1 CSV 輸出用於管線處理

所有 list 指令都支援 -v / --csv 輸出，方便 pipe 給其他工具：

1kaggle datasets list -s "nlp" -v | head -5
2kaggle competitions list --category featured -v | cut -d, -f1,2

8.2 設定預設值減少輸入

1kaggle config set -n competition -v titanic
2kaggle config set -n path -v ~/kaggle-data
3
4# 之後不需要 -c 和 -p 參數
5kaggle competitions download
6kaggle competitions submit -f submission.csv -m "test"

8.3 Kernel 自動化

1# 初始化 kernel metadata
2kaggle kernels init -p ./my-notebook
3
4# 編輯 kernel-metadata.json 設定 GPU / 依賴
5# 推送並自動執行
6kaggle kernels push -p ./my-notebook
7kaggle kernels status username/my-notebook

8.4 搭配 Agent Skill

Kaggle CLI 內建 skills/SKILL.md，AI agent 可自動發現。安裝到 Claude Code skills 目錄後，agent 就能直接操作 Kaggle：

1cp -r skills/ ~/.claude/skills/kaggle-cli/

9. 整合進其他工作流

搭配 Jupyter Notebook

在 notebook 中使用 ! 前綴呼叫 CLI：

1!kaggle competitions download -c titanic
2import pandas as pd
3df = pd.read_csv("titanic/train.csv")

搭配 DVC / MLflow

將 Kaggle 資料集整合進 ML pipeline：

1# DVC
2dvc import-url kaggle://owner/dataset ./data
3# 或直接下載後用 dvc add 追蹤
4kaggle datasets download -d owner/dataset -p ./data
5dvc add ./data

搭配 AI-knowledge_template

Kaggle 資料集的 metadata 可存入 inbox/，再走 graphify / paper-qa-lite 等 layer 分析。

10. 重點摘要 Checklist

安裝：pip install kaggle（Python 3.11+）
認證：推薦 kaggle auth login（OAuth），CI 用環境變數
10 大命令群組：competitions / datasets / kernels / models / forums / benchmarks / config / auth / quota / files
競賽工作流：list → download → train → submit → leaderboard
資料集管理：init → create → version（更新）
CSV 輸出：-v flag 方便管線處理
預設值：config set 減少重複輸入
Benchmarks：v2.2+ LLM 基準測試功能
Agent Skill：內建 SKILL.md，AI agent 可自動發現
安全：auth file 設 chmod 600，CI 用環境變數

Kaggle CLI 完整教學 — 從認證設定到競賽提交的全方位操作指南

Contents