gem-hunter

The official CLI to interact with Kaggle.

User documentation

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.

Install the kaggle package with pip:

pip install kaggle

Additional installation instructions can be found here.

Explore the available commands by running:

kaggle --help

See the User documentation for more examples & tutorials.

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.

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.

We use hatch to manage this project.

Follow these instructions to install it.

hatch run kaggle datasets list

hatch shell

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

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

# Format
hatch run lint:fmt

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

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

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).

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.

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.

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

See CHANGELOG.

See CONTRIBUTING.md.

The Kaggle CLI is released under the Apache 2.0 license.