Hosting a Competition from the CLI

This page documents the host-facing commands added in kaggle-cli for the new public competition-creation API endpoints (kagglesdk 0.1.31+):

kaggle competitions init
kaggle competitions create
kaggle competitions pages create
kaggle competitions hosts
kaggle competitions settings get
kaggle competitions settings update
kaggle competitions data update
kaggle competitions solution create
kaggle competitions solution status
kaggle competitions launch

All of these commands require an authenticated session (kaggle config set username/password or an API token).

A typical end-to-end host workflow looks like:

# 1. Scaffold a metadata file.
kaggle competitions init ./my-comp

# 2. Edit ./my-comp/competition-metadata.json (fill in the INSERT_* placeholders).

# 3. Create the (unlaunched) competition.
kaggle competitions create -p ./my-comp
# → Competition created: https://www.kaggle.com/competitions/my-comp-slug

# 4. Author the description and rules pages.
kaggle competitions pages create my-comp-slug --name description -f ./description.md --publish
kaggle competitions pages create my-comp-slug --name rules -f ./rules.md --publish

# 5. Update the competition data (train.csv, test.csv, sample_submission.csv, ...).
kaggle competitions data update my-comp-slug -p ./data -m "Initial release"

# 6. Upload the private solution CSV, then poll until scoring is ready.
kaggle competitions solution create my-comp-slug -p ./solution.csv
kaggle competitions solution status my-comp-slug
# → Ready: true

# 7. Optionally tune host-only settings not covered by competition-metadata.json
#    (deadlines, runtime caps, leaderboard behavior, etc.).
kaggle competitions settings get my-comp-slug
kaggle competitions settings update my-comp-slug -f ./settings.json

# 8. Launch the competition (now, or schedule a future UTC time).
kaggle competitions launch my-comp-slug --at 2027-01-01T00:00:00Z

These commands are independent — for example, you can call pages create on a competition that already exists, or use launch on a competition created via the host wizard.

`kaggle competitions init`

Writes a competition-metadata.json template into a folder.

Usage:

kaggle competitions init [folder]

Arguments:

folder (optional): Where to write competition-metadata.json. Defaults to the current directory.

Example:

kaggle competitions init ./my-comp

The generated file:

{
  "title": "INSERT_TITLE_HERE",
  "slug": "INSERT_SLUG_HERE",
  "briefDescription": "INSERT_BRIEF_DESCRIPTION_HERE",
  "privacy": "PUBLIC",
  "disableKernels": false,
  "hackathon": false,
  "cloneCompetitionId": null,
  "cloneExcludeCompetitionData": null,
  "clonePageNames": null,
  "licenseId": null,
  "organizationId": null,
  "numPrizes": null,
  "restrictLinkToEmailList": null,
  "reward": null
}

See Metadata reference below for what each field means.

`kaggle competitions create`

Creates a new competition from competition-metadata.json. The competition is created in an unlaunched (staged) state — use kaggle competitions launch to publish it.

Usage:

kaggle competitions create [-p folder]

Options:

-p, --path <folder>: Folder containing competition-metadata.json. Defaults to the current directory.

Example:

kaggle competitions create -p ./my-comp
# → Competition created: https://www.kaggle.com/competitions/my-comp-slug

Errors you might see:

Default title detected, please update competition-metadata.json before creating — you forgot to replace one of the INSERT_*_HERE placeholders.
Invalid privacy '...' — privacy must be one of PUBLIC, LIMITED, PRIVATE.
Metadata file not found: competition-metadata.json — run init first, or pass -p pointing at the folder that contains the file.

Competition metadata reference

All fields go in competition-metadata.json (camelCase keys).

Required:

Field	Type	Notes
`title`	string	Display title shown on the competition page.
`slug`	string	URL slug; lowercase, hyphens, must be unique site-wide and must not be all digits or all hyphens.
`briefDescription`	string	One-line subtitle under the title.
`privacy`	string	One of `PUBLIC`, `LIMITED`, `PRIVATE`.

Optional:

Field	Type	Notes
`disableKernels`	bool	If `true`, notebook submissions are disabled.
`hackathon`	bool	Create as a hackathon competition.
`restrictLinkToEmailList`	bool	Restrict invite-link joiners to a host-maintained allowlist.
`cloneCompetitionId`	int	If set, clone configuration / pages / data / evaluation setup from this competition.
`cloneExcludeCompetitionData`	bool	If cloning, skip copying the data (solution, sandbox submissions, images, databundles).
`clonePageNames`	string[]	If cloning, copy only these page names. Omit/null to copy all.
`licenseId`	int	License ID for the competition data.
`organizationId`	int	Tie this competition to an organization (read-only access for all org members).
`numPrizes`	int	Number of leaderboard prize positions.
`reward`	object	See below.

reward object:

{
  "id": "USD",
  "quantity": 25000,
  "clarification": "Total prize pool split across the top 5 teams."
}

reward.id is one of: USD, KUDOS, AUD, EUR, JOBS, SWAG, GBP, KNOWLEDGE, PRIZES. clarification is optional free-form text shown next to the prize.

`kaggle competitions pages create`

Creates a new page (description, rules, evaluation, data-description, etc.) on a competition you host.

Usage:

kaggle competitions pages create <competition> --page-name <page-name> -f <path> \
    [--mime-type <type>] [--post-title "<title>"] [--publish]

Arguments:

<competition>: The competition slug.

Options:

--page-name <page-name> (required): Page name (e.g. description, rules, evaluation, data-description, prizes). Conventional names are recognized by the competition page UI; new names are allowed but won't be shown in the standard tabs.
-f, --file <path> (required): Path to a file whose contents become the page body.
--mime-type <type> (optional): MIME type of the content. Defaults to text/html server-side.
--post-title "<title>" (optional): Title shown above the page body. Defaults to the page name.
--publish (optional): Publish the page immediately. Without this flag the page is created in a staged (unpublished) state so you can review it before going live.

Example:

# Create the rules page in a staged (not-yet-published) state.
kaggle competitions pages create my-comp --page-name rules -f ./rules.md \
    --mime-type text/markdown --post-title "Competition Rules"

# When you're ready to make it visible to participants:
kaggle competitions pages update my-comp --page-name rules --publish

Each page exists as a single record; --publish / --unpublish toggles its visibility rather than creating separate draft and live copies. To swap in new content later, use kaggle competitions pages update — a second create for the same page name will be rejected.

You can list and inspect existing pages with kaggle competitions pages (or the explicit kaggle competitions pages list), modify one in place with kaggle competitions pages update, or remove one with kaggle competitions pages delete.

`kaggle competitions pages update`

Updates fields on an existing competition page. Only the flags you supply are sent (the FieldMask is built from which arguments are non-default), so this is also how you publish or unpublish a page in place.

Usage:

kaggle competitions pages update <competition> --page-name <current-name> \
    [-f <path>] [--new-name <name>] [--mime-type <type>] \
    [--post-title "<title>"] [--publish | --unpublish]

Arguments:

<competition>: The competition slug.

Options:

--page-name <current-name> (required): The page's current name (used as the identifier; rename via --new-name).
-f, --file <path> (optional): Path to a file with the new page body.
--new-name <name> (optional): Rename the page.
--mime-type <type> (optional): New MIME type of the content.
--post-title "<title>" (optional): New title shown above the page content.
--publish / --unpublish (optional, mutually exclusive): Publish or unpublish the page.

At least one update flag is required.

Examples:

# Publish a staged page without changing its content.
kaggle competitions pages update my-comp --page-name rules --publish

# Swap in new content and update the visible title in one call.
kaggle competitions pages update my-comp --page-name rules \
    -f ./rules-v2.md --post-title "Competition Rules (v2)"

# Rename a page.
kaggle competitions pages update my-comp --page-name evaluation \
    --new-name scoring

Note: a small set of pages is reserved by the backend and cannot be renamed; attempting to rename one returns an error from the server.

`kaggle competitions pages delete`

Deletes a page from a competition you host. Prompts for confirmation unless -y/--yes is passed (matches the existing kaggle datasets delete / kaggle kernels delete patterns).

Usage:

kaggle competitions pages delete <competition> --page-name <name> [-y]

Arguments:

<competition>: The competition slug.

Options:

--page-name <name> (required): Name of the page to delete.
-y, --yes (optional): Skip the confirmation prompt — useful for scripts.

Examples:

# Interactive: prompts "Are you sure you want to delete the page 'faq' ...?"
kaggle competitions pages delete my-comp --page-name faq

# Scripted: skip the prompt.
kaggle competitions pages delete my-comp --page-name faq -y

Note: a small set of pages is protected by the backend and cannot be deleted; attempting to delete one returns an error from the server.

Deletion is not recoverable — there is no "undelete". List pages first with kaggle competitions pages list <competition> if you're unsure of the name.

`kaggle competitions hosts`

Lists the hosts (users with host access) for a competition. Useful for confirming who can edit settings, upload data, or launch — especially after adding or removing collaborators via the web UI.

Usage:

kaggle competitions hosts <competition> [-v | --format json]

Arguments:

<competition>: The competition slug.

Examples:

# Table output.
kaggle competitions hosts my-comp

# CSV — useful for piping into other tools.
kaggle competitions hosts my-comp -v

# JSON.
kaggle competitions hosts my-comp --format json

Output columns: userName, displayName, id, profileUrl.

`kaggle competitions settings get`

Shows the unified settings blob for a competition you host — the same set of fields the "Settings" tab exposes in the web UI, covering general info, access & teams, key dates, submissions & leaderboard behavior, code competition parameters, and host attribution.

By default the output is grouped by UI section and hides fields left at their type default (unset strings, false booleans, zero ints). Pass --json for the raw blob (camelCase keys, matching the update payload format).

Usage:

kaggle competitions settings get <competition> [--json]

Arguments:

<competition>: The competition slug.

Examples:

# Grouped, human-readable summary.
kaggle competitions settings get my-comp

# Machine-readable dump — pipe into jq, or save + edit + feed back to update.
kaggle competitions settings get my-comp --json > settings.json

`kaggle competitions settings update`

Applies a partial update to a competition's settings. You author a JSON or YAML file containing only the fields you want to change; the CLI builds the server-side FieldMask from the keys present in the file, so unspecified fields are left alone.

The typical loop is:

kaggle competitions settings get my-comp --json > settings.json — pull the current values.
Edit the file down to just the fields you want to change (delete the rest).
kaggle competitions settings update my-comp -f ./settings.json.

Usage:

kaggle competitions settings update <competition> -f <path> [--json]

Arguments:

<competition>: The competition slug.

Options:

-f, --from-file <path> (required): JSON or YAML file with the fields to update. Extension picks the parser (.yaml/.yml → YAML, anything else → JSON). Keys may be snake_case (matches the SDK) or camelCase (matches the --json output of settings get).
--json (optional): After the update, print the returned settings as JSON instead of the grouped text view.

Examples:

Toggle a single boolean:

// disable-leaderboard.json
{ "has_leaderboard": false }

kaggle competitions settings update my-comp -f ./disable-leaderboard.json

Set the competition deadline:

// deadline.json
{ "deadline": "2027-02-01T23:59:00Z" }

kaggle competitions settings update my-comp -f ./deadline.json

Bump the code-competition runtime caps and set the competition and team-merger deadlines (YAML, mixing types):

# tune.yaml
max_cpu_runtime_minutes: 540
max_gpu_runtime_minutes: 720
deadline: 2027-02-01T23:59:00Z
team_merger_explicit_deadline: 2027-01-15T00:00:00Z
rules_required: true

kaggle competitions settings update my-comp -f ./tune.yaml

Type notes:

Booleans → JSON true/false (or YAML equivalents).
Numeric fields → plain numbers (240, 1.5).
Datetime fields → ISO-8601 strings ("2027-01-01T00:00:00Z" or with an explicit offset).
Enum fields (host_segment, publicly_cloneable) → the enum member name as a string; either the full name ("HOST_SEGMENT_FEATURED") or the short suffix ("FEATURED") works.

Common errors:

Unknown competition setting: '<name>' — the field name isn't in CompetitionSettings. Check settings get --json for the exact keys.
Field '<name>' expects a bool, got str — the file has a string where a boolean is required (e.g. "true" instead of true).
not a valid HostSegment. Allowed: ... — the enum value you passed isn't a member; the error lists the accepted names.
Some settings are gated to Kaggle admins (marked "ADMIN ONLY" in the proto — e.g. host_segment, directly_responsible_user_id) and the server will reject writes to them for non-admin hosts.

`kaggle competitions launch`

Launches a competition you host. Without --at, the competition is launched immediately. With --at, the backend schedules the launch for the given UTC instant.

Usage:

kaggle competitions launch <competition> [--at <ISO-8601 UTC>]

Arguments:

<competition>: The competition slug.

Options:

--at <iso>: Schedule launch for a future UTC time. Accepts ISO-8601 (e.g. 2027-01-01T00:00:00Z or 2027-01-01T00:00:00+00:00). The competition is launched immediately if omitted.

Examples:

# Launch right now.
kaggle competitions launch my-comp

# Schedule the launch for midnight UTC on 2027-01-01.
kaggle competitions launch my-comp --at 2027-01-01T00:00:00Z

A competition can only be launched once. Subsequent calls will be rejected by the backend.

`kaggle competitions data update`

Creates a new version of the data files for a competition you host. Uploads via the standard blob-upload pipeline, then sends a single request bundling the uploaded tokens. Each update replaces the prior version's file set in full — there is no per-file "keep from previous" mode in v1, so list every file you want in the new version.

Usage:

kaggle competitions data update <competition> -p <path> -m "<version notes>" \
    [--rerun] [--include-hidden] [--ignore-patterns <patterns>]

Arguments:

<competition>: The competition slug.

Options:

-p, --path <path> (required): Either a directory (walked recursively — every file becomes an upload with its relative path preserved in the API's name field, e.g. train/images/img1.jpg), or a single archive file (e.g. a pre-packed .zip or .tar) uploaded as-is. Sub-directories are always traversed; hidden entries (see --include-hidden) are the only files skipped by default.
-m, --message "<notes>" (required): Notes describing this version (e.g. "Added test set").
--rerun (optional): Update the RERUN databundle — the private host-only data swapped in during rerun scoring. Requires Kaggle admin access for now. Without this flag, the update targets the PUBLIC databundle (what participants download).
--include-hidden (optional): Upload hidden files and traverse hidden sub-directories (names starting with . — e.g. .DS_Store, .git/, .gitignore). Skipped by default so you don't accidentally publish OS metadata or version-control detritus.
--ignore-patterns <patterns> (optional): Patterns to ignore when uploading files/dirs. Can be specified multiple times. Note that default ignore patterns (like .git/, .cache/, .huggingface/) are bypassed when --include-hidden is True.

Examples:

# Update using a directory tree (recurses into sub-folders).
kaggle competitions data update my-comp -p ./data -m "Initial release"

# Update using a pre-packed archive as a single file (useful when you already
# need a zip for other purposes, or for directory-shaped file formats like
# Zarr).
kaggle competitions data update my-comp -p ./data.zip -m "Initial release"

# New version with a bug-fix.
kaggle competitions data update my-comp -p ./data -m "Fix label encoding in train.csv"

# Update the private rerun-scoring data.
kaggle competitions data update my-comp -p ./rerun-data \
    -m "Held-out test set" --rerun

A note on directory-shaped file formats: some formats (Zarr, some TensorFlow SavedModel layouts, etc.) are on-disk directories that are logically a single unit. If you pass a directory containing such a format, the recursive walk uploads each internal chunk as its own file — often what you want for Zarr, since participants can then stream individual chunks. If you'd rather keep the format as an opaque single upload, pre-pack it into a .zip or .tar and pass that file to -p instead.

The command prints the public URL plus the new databundle_id and databundle_version_id on success.

`kaggle competitions solution create`

Uploads the private solution CSV for a competition you host. The solution is what the backend scores submissions against — one row per row in the sample submission, with the same column shape. After uploading, the backend runs preprocessing / sampling; poll kaggle competitions solution status until it's ready before opening submissions.

The file is uploaded via the standard blob-upload pipeline, then the resulting token is passed to CreateCompetitionSolution.

Usage:

kaggle competitions solution create <competition> -p <path> [-q]

Arguments:

<competition>: The competition slug.

Options:

-p, --path <path> (required): Path to a single CSV file. Must be a single file — directories are rejected. The CSV shape must match a submission file (same columns as sample_submission.csv).
-q, --quiet (optional): Suppress per-file upload progress lines.

Example:

kaggle competitions solution create my-comp -p ./solution.csv
# → Solution uploaded for "my-comp". Run 'kaggle competitions solution status my-comp' to check readiness.

Re-uploading a solution replaces the prior one. Note that this only works pre-launch; after launch the solution file is frozen.

`kaggle competitions solution status`

Shows the setup status for a competition's solution file — whether preprocessing/sampling has finished, any errors reported by the backend, and (for legacy C# metrics) the auto-inferred column mapping and required metric columns.

Poll this after solution create (and after data update — some setup steps run against the databundle) until Ready: true. If Setup error: is set, stop polling and fix the underlying issue.

Usage:

kaggle competitions solution status <competition> [--json]

Arguments:

<competition>: The competition slug.

Options:

--json (optional): Emit the raw status as JSON instead of the human-readable view.

Examples:

# Human-readable summary.
kaggle competitions solution status my-comp
# → Ready: true
#   Solution file: solution.csv — 12.3KB — uploaded 2027-01-01T00:00:00+00:00
#     total=1000, public=300, private=700

# Machine-readable — useful in a polling loop.
kaggle competitions solution status my-comp --json

Fields you might see (human view):

Ready: true|false — whether scoring is unblocked.
Setup error: <msg> — populated if preprocessing failed. Surfaced prominently; stop polling when it appears.
Kernels metric: true — the competition's scoring metric is a Kernels metric. Kernels metrics auto-detect their column mapping; the host only needs to wait for Ready to flip true.
Row ID column: <name> — for Kernels metrics, the auto-detected row-id column.
Solution file: <name> — <size> — uploaded <timestamp> and total=..., public=..., private=... — solution file metadata once the upload is processed.
Column mapping: — for legacy C# metrics, the current mapping from metric column name to CSV column name.
Required columns: — for legacy C# metrics, the metric column slots the host needs to fill (name + expected data type).

Navigation Menu

Uh oh!

Hosting a Competition from the CLI

`kaggle competitions init`

`kaggle competitions create`

Competition metadata reference

`kaggle competitions pages create`

`kaggle competitions pages update`

`kaggle competitions pages delete`

`kaggle competitions hosts`

`kaggle competitions settings get`

`kaggle competitions settings update`

`kaggle competitions launch`

`kaggle competitions data update`

`kaggle competitions solution create`

`kaggle competitions solution status`

Uh oh!

FilesExpand file tree

competition_creation.md

Latest commit

History

competition_creation.md

File metadata and controls

Hosting a Competition from the CLI

kaggle competitions init

kaggle competitions create

Competition metadata reference

kaggle competitions pages create

kaggle competitions pages update

kaggle competitions pages delete

kaggle competitions hosts

kaggle competitions settings get

kaggle competitions settings update

kaggle competitions launch

kaggle competitions data update

kaggle competitions solution create

kaggle competitions solution status

`kaggle competitions init`

`kaggle competitions create`

`kaggle competitions pages create`

`kaggle competitions pages update`

`kaggle competitions pages delete`

`kaggle competitions hosts`

`kaggle competitions settings get`

`kaggle competitions settings update`

`kaggle competitions launch`

`kaggle competitions data update`

`kaggle competitions solution create`

`kaggle competitions solution status`