Run with Kaggle

Run local workspace files in a remote Kaggle GPU/TPU Kernel directly from VS Code — a VS Code extension.

[!IMPORTANT] Prerequisite: You need a Kaggle account and an API token. To obtain one, log into Kaggle, go to your Kaggle Settings Page, scroll down to the API section, and click Create New Token (which downloads a kaggle.json containing your key) or copy your bearer token.

Execution Modes

This extension provides two main execution flows to run your code on Kaggle's remote hardware accelerators (such as Nvidia Tesla T4 or P100 GPUs):

1. Run Workspace with Kaggle (Zip as Dataset)

• How it works: The extension compresses your local workspace folder (automatically respecting .gitignore and .kaggleignore files), uploads it as a private Kaggle Dataset version, and starts a remote Kaggle Notebook. The notebook automatically extracts your workspace, installs required dependencies, and executes your Python script.
• Benefits: This allows you to run complex codebases exactly like you do locally but powered by remote GPUs/TPUs. All your files, local imports, helper modules, and custom configuration files in the workspace are fully preserved and accessible in the remote Kaggle notebook environment.

2. Run Notebook with Kaggle (Direct Notebook Execution)

• How it works: The extension takes a raw Jupyter Notebook (.ipynb file) and pushes its cell contents directly as a Kaggle Notebook Kernel.
• Benefits: It completely skips the file packaging, workspace zipping, and dataset upload stages. This is ideal for quickly and cleanly running isolated standalone notebooks using remote Kaggle accelerators.

Table of Contents

• Execution Modes
• Features
• Credentials Setup
• How to Use
• Configuration
• Development
• License

Features

Seamless Execution

• Status Bar Integration — one-click status bar command to trigger runs on the active Python file.
• Smart Prompts — prompts you for command-line arguments and extra pip packages before execution.
• Persistent Preferences — remembers your last used arguments, extra pip packages, accelerator options, and workspace zip custom ignore rules per workspace/file.

Workspace Packaging & Filtering

• Dynamic Zip Exclusions — automatically respects .gitignore and .kaggleignore patterns.
• Interactive Rules Customizer — supports custom inclusions (+path/) and exclusions (-path/) with proper recursive matching (e.g. +checkpoints/ will un-ignore all files inside the directory).
• Size Optimization — skips obvious generated and runtime files (like node_modules/, venv/, __pycache__/) by default to keep dataset uploads small and fast.

Robust Client & Automation

• Native REST API Client — performs communication entirely over direct HTTP requests, avoiding any Python environment dependencies.
• Automatic Rerun on Missing Modules — detects errors such as ModuleNotFoundError: No module named 'tyro', maps the import name to the correct pip package (e.g. cv2 to opencv-python, pil to Pillow), prompts you for verification, and automatically updates and resubmits the run.
• Live Logs & Status Tracking — streams notebook logs in real-time inside a custom VS Code webview panel or output channel.
• Smart Cancellation — responsive cancellation checks that warning you the remote Kaggle run continues to execute and provides a direct shortcut button to the Kaggle web interface to stop it.

Credentials Setup

To use this extension, you need a Kaggle account and an API token. Generate one at Kaggle Settings.

The extension checks credentials in the following order:

1. runWithKaggle.apiToken (configured in settings)
2. runWithKaggle.username and runWithKaggle.apiKey
3. VS Code Secret Storage (from the guided setup when credentials are missing)
4. Environment variable KAGGLE_API_TOKEN
5. ~/.kaggle/access_token
6. <workspace>/.kaggle/access_token
7. ~/.kaggle/kaggle.json
8. <workspace>/.kaggle/kaggle.json

Guided Credential Setup

If no credentials are found, the extension will prompt you to enter them. Your username will be saved in VS Code User Settings, and your token/key will be saved securely in the VS Code Secret Storage (never stored as plaintext).

How to Use

Run a Python Script (Workspace Mode)

1. Open your project in VS Code and open the .py script you want to run.
2. Click the status bar button $(cloud-upload) Run with Kaggle, click the Run with Kaggle button at the top-right editor toolbar, or right-click the file and select Run with Kaggle.
3. Specify your script command (e.g. python main.py), package requirements, accelerator, and packaging ignore rules.
4. The extension will automatically zip the workspace, upload it to Kaggle as a private dataset, submit the kernel, and stream execution logs.

Run a Jupyter Notebook (Direct Mode)

1. Open a Jupyter Notebook (.ipynb file) in VS Code.
2. Click the Run Notebook with Kaggle button at the top-right editor toolbar, or right-click the file and select Run Notebook with Kaggle.
3. Select your hardware accelerator.
4. The extension will push your notebook cell contents directly as a Kaggle kernel and poll the remote execution.

Configuration

The extension can be customized in VS Code Settings (settings.json):

Development

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Watch mode (automatic compilation)
npm run watch

Press F5 in VS Code to open a new Extension Development Host window and test the extension.

License

MIT — see LICENSE for details.