kagglex

Execute local Python code, modules, and experiments seamlessly on Kaggle GPUs and TPUs.

Overview

kagglex enables machine learning practitioners and researchers to transparently package and dispatch local Python code, standalone scripts, or complete packages to Kaggle's cloud GPU and TPU environments without tedious manual uploading or notebook maintenance.

Features

• Flexible project detection for standalone scripts, flat packages, or src/ layout projects
• Pre-flight validation with local AST syntax checking and credential verification
• Automatic ignore filtering powered by pathspec supporting .gitignore and .kaggleignore
• Dual-tier packaging preventing bloated uploads and base64 truncation
• Automated multi-GPU execution using torchrun
• Secure Kaggle Secrets integration for WandB, HuggingFace, and custom credentials
• Local experiment history repository for tracking past runs, statuses, and durations
• Interactive REPL execution on active Kaggle notebooks via Jupyter proxy URL
• Programmatic Python SDK alongside the kagglex CLI

Installation

Install via uv or pip:

uv pip install kagglex

CLI Usage

Run a Standalone Script

kagglex run --file train.py --gpu t4-2x --title "Pilot Training"

Run a Module with Multi-GPU

kagglex run "python -m mypkg.train --epochs 10" --gpu t4-2x --multi-gpu

Stream Remote Logs in Real-Time

kagglex run "python train.py" --stream

List Recent Runs

kagglex list

Check Status or Cancel a Run

kagglex status my-experiment
kagglex cancel my-experiment

Pull Downloaded Outputs

kagglex pull my-experiment --output-dir ./results --include-outputs "*.json" "checkpoints/*"

Push a Kaggle Dataset

kagglex dataset push --data-dir ./data/embeddings --title "Embeddings Dataset"

Interactive REPL on Running Kaggle Notebooks

When a notebook is already open in Kaggle, copy its proxy URL (Run -> Kaggle Jupyter Server -> Copy URL) and run commands with sub-second feedback:

# Verify connection
kagglex exec --url "https://kkb-production.jupyter-proxy.kaggle.net?token=..." --test

# Query remote GPU status
kagglex exec --url "https://kkb-production.jupyter-proxy.kaggle.net?token=..." --gpu-info

# Execute inline Python snippets
kagglex exec "import torch; print(torch.cuda.device_count())"

# Execute a local Python file remotely
kagglex exec --file evaluate.py

# List and transfer files
kagglex exec --list-files
kagglex exec --upload ./checkpoint.pt
kagglex exec --download run_results.json -o ./local_results.json

Alternatively, set the environment variable:

export KAGGLE_JUPYTER_URL="https://kkb-production.jupyter-proxy.kaggle.net?token=..."

Python SDK Usage

from kagglex import KaggleRunner, RunConfig

runner = KaggleRunner()
job = runner.run(
    command="python -m mypkg.train --batch-size 64",
    title="Fine Tuning Run",
    gpu="t4-2x",
    multi_gpu=True,
    wait=True,
)

print(f"Status: {job.status}")
job.pull_outputs(destination_dir="./results")