Run with Kaggle

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

Zip your active workspace, upload it as a private Kaggle Dataset, and spin up a remote Kaggle Notebook with hardware accelerators (GPU/TPU) to run your Python module — all without leaving VS Code and without relying on the Python kaggle CLI.

Table of Contents

• 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

1. Open your Python project in VS Code.
2. Open the Python script you want to run.
3. Click the status bar button $(cloud-upload) Run with Kaggle or right-click in the editor/explorer and choose Run with Kaggle.
4. Configure your parameters (arguments, pip packages, requirements.txt, accelerator, and zip rules).
5. The extension will package your workspace, upload the dataset (waiting for it to be ready), submit the kernel, and stream the logs.

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.