kagglehub

The behavior of kagglehub depends on whether you are running code inside a Kaggle notebook or in a local environment:

In a Kaggle notebook:

• Resources are automatically attached to your notebook.
• Resources appear under the "Input" panel in the Kaggle notebook editor.
• Files are served from the shared Kaggle resources cache rather than the VM's disk.

Outside a Kaggle notebook:

• Resource files are downloaded to a local cache folder.

To use VS Code with the project's hatch managed environments, follow these steps:

1. Configure hatch to create virtual environments within the project folder:

   hatch config set dirs.env.virtual .

2. Create the necessary Python environments by running all tests:

   hatch test --all

3. In VS Code, open the Command Palette (cmd + shift + p), select Python: Select Interpreter, and pick an environment from the ./.env folder.

Authentication is required to access public resources requiring user consent or private resources. kagglehub is authenticated by default when running in a Kaggle notebook.

To authenticate manually, you can use one of the following methods:

1. Interactive Login: Call kagglehub.login() to be prompted for your Kaggle API token.
2. Environment Variable: Export KAGGLE_API_TOKEN with your token value.
3. API Token File: Place your token in ~/.kaggle/access_token.
4. Google Colab Secret: Store your token in a Colab secret named KAGGLE_API_TOKEN.
5. Legacy API Credentials: Place a kaggle.json file at ~/.kaggle/kaggle.json.

import kagglehub

# Option 1: Interactive login
kagglehub.login()

Install the kagglehub package using pip to interact with Kaggle datasets, models, and notebook outputs in Python.

pip install kagglehub

By default, kagglehub downloads files to ~/.cache/kagglehub/. You can override this location by setting the KAGGLEHUB_CACHE environment variable.

export KAGGLEHUB_CACHE=/path/to/your/custom/cache

By default, kagglehub uses a standard system cache folder. You can redirect all cache operations to a specific directory by passing the override_dir argument to the Cache constructor. This is useful for managing disk space or working in environments with restricted write permissions.

When an override_dir is provided, get_path and get_archive_path will resolve paths relative to this directory instead of the default Kaggle cache location.

from kagglehub.cache import Cache

# All downloaded resources will be stored in this specific folder
cache = Cache(override_dir="/mnt/data/kaggle_cache")

By default, kagglehub is configured for console logging. To enable file-based logging, set the KAGGLE_LOGGING_ENABLED environment variable to 1.

Logs will be written to a directory resolved via os.path.expanduser. The default log paths are:

• macOS: /user/$USERNAME/.kaggle/logs/kagglehub.log
• Linux: ~/.kaggle/logs/kagglehub.log
• Windows: C:\Users\%USERNAME%\.kaggle\logs\kagglehub.log

You can override the root log directory by setting the KAGGLE_LOGGING_ROOT_DIR environment variable.

Use kagglehub.dataset_download() to download Kaggle datasets. You can download entire datasets, specific versions, single files, or directories while preserving structure.

Key Parameters:

• handle: The dataset handle.
• path: (Optional) Specific file or directory path within the dataset.
• force_download: (Optional) Boolean to force re-download.
• output_dir: (Optional) Custom local directory for the download.

import kagglehub

# Download latest version
kagglehub.dataset_download('bricevergnou/spotify-recommendation')

# Download specific version
kagglehub.dataset_download('bricevergnou/spotify-recommendation/versions/1')

# Download a single file to a custom directory
kagglehub.dataset_download('bricevergnou/spotify-recommendation', path='data.csv', output_dir='./data')

Use kagglehub.model_upload() to upload a new model variation or version.

Parameters:

• handle: The target handle in the format <KAGGLE_USERNAME>/<MODEL>/<FRAMEWORK>/<VARIATION>.
• local_model_dir: The path to your local model directory.
• version_notes: (Optional) String describing the version.
• license_name: (Optional) The license for the model.
• ignore_patterns: (Optional) A list of file/directory patterns to exclude (e.g., ["original/", "*.tmp"]).

import kagglehub

handle = '<KAGGLE_USERNAME>/<MODEL>/<FRAMEWORK>/<VARIATION>'
local_model_dir = 'path/to/local/model/dir'

# Basic upload
kagglehub.model_upload(handle, local_model_dir)

# Upload with metadata and ignore patterns
kagglehub.model_upload(
    handle, 
    local_model_dir, 
    version_notes='improved accuracy',
    license_name='Apache 2.0',
    ignore_patterns=["original/", "*.tmp"]
)

You can install Kaggle utility scripts directly into your Python environment using kagglehub.utility_script_install(). This makes the code from the script available for import/use in your current session.

import kagglehub

# Install the latest version of a utility script
kagglehub.utility_script_install('bjoernjostein/physionet-challenge-utility-script')