Kaggle/kaggle-cli

Kaggle CLI

The official CLI to interact with Kaggle.

User documentation

Key Features

Some of the key features are:

• List competitions, download competition data, submit to a competition.
• List, create, update, download or delete datasets.
• List, create, update, download or delete models & model variations.
• List, update & run, download code & output or delete kernels (notebooks).
• Browse and read discussion forums.

Installation

Install the kaggle package with pip:

pip install kaggle

Additional installation instructions can be found here.

Quick start

Explore the available commands by running:

kaggle --help

See the User documentation for more examples & tutorials.

Hosting a competition

End-to-end host commands — scaffold a new competition, author its pages, tune its settings, and launch it — are documented in docs/competition_creation.md. Covers kaggle competitions init, create, pages create, hosts, settings get, settings update, and launch.

Development

kagglesdk Updates

New features that interact with kaggle.com probably require changes to the Python library, kagglesdk. Make sure to bump the minimum version required for kagglesdk in the dependencies list specified in [pyproject.toml][pyproject.toml]]. Make sure the required version is available on the pypi.org kagglesdk project.

Prerequisites

We use hatch to manage this project.

Follow these instructions to install it.

Run kaggle from source

Option 1: Execute a one-liner of code from the command line

hatch run kaggle datasets list

Option 2: Run many commands in a shell

hatch shell

# Inside the shell, you can run many commands
kaggle datasets list
kaggle competitions list
...

Lint / Format

# Lint check
hatch run lint:style
hatch run lint:typing
hatch run lint:all     # for both

# Format
hatch run lint:fmt

Tests

Note: These tests are not true unit tests and are calling the Kaggle web server.

# Run against kaggle.com
hatch run test:prod

# Run against a local web server (Kaggle engineers only)
hatch run test:local

Integration Tests

To run integration tests on your local machine, you need to set up your Kaggle credentials. You can do this by following the authentication instructions.

After setting up your credentials, you can run the integration tests as follows:

hatch run test:integration

Code Coverage

We measure code coverage using pytest-cov.

To run unit tests with coverage and generate reports:

hatch run test:cov

This generates:

• Terminal output with a coverage summary.
• coverage.xml (XML report in the root, used by IDE integrations).
• htmlcov/index.html (HTML report for browser viewing).

Editor Integration

VSCode

Install the Coverage Gutters extension. After running the coverage command, click the Watch button in the status bar to see coverage indicators in the editor margins.

JetBrains Rider

With the Python plugin installed:

• Run with Coverage: Create a Pytest run configuration and click the shield icon ("Run with Coverage").
• Import Report: Go to Tools -> Show Code Coverage Data, click Add (+), and select coverage.xml.

Running hatch commands inside Docker

This is useful to run in a consistent environment and easily switch between Python versions.

The following shows how to run hatch run lint:all but this also works for any other hatch commands:

# Use default Python version
./docker-hatch run lint:all

Changelog

See CHANGELOG.

Contributing

See CONTRIBUTING.md.

License

The Kaggle CLI is released under the Apache 2.0 license.