Skip to main content

​
Name

nebius ai job run

Package a local Python script and run it on a freshly provisioned Nebius VM as a
one-off Job, streaming the container logs to stdout and following the job to
completion.

Inputs:
<file.py> The entry script to run. It can also be set as ‘entry’ in
nebius.yaml. Its whole directory is packaged and shipped, so
imports of sibling modules work.
the directory Everything next to the script is gzip-packed and must fit
≤64 KiB compressed. A built-in ignore set (virtualenvs,
Python caches, VCS metadata, *.pyc, .DS_Store, …) and an
optional .nebiusignore (a subset of .gitignore syntax) are
excluded. Preview the exact set with —show-context.
dependencies Go via a bundled requirements.txt (pip-installed before the
script) or a prebuilt —image — NOT as files. Do not ship a
virtualenv; its binaries won’t run on the VM.
— args… Everything after ’—’ is passed to the script unchanged as
sys.argv (e.g. ‘run main.py — —epochs 10’).

Behavior for automation:

  • In foreground mode, stdout carries only the job’s container logs.
    Job ID, progress, artifact hints, and the BETA banner go to stderr.
  • With —detach, explicit —format json or yaml returns the full Operation
    on stdout. Its id identifies the operation; resource_id identifies the Job.
    Use --format 'jsonpath={.resource_id}' to extract the Job ID.
    Without these formats, stdout is empty.
  • The command blocks until the job reaches a terminal state, then exits with a
    code derived from that state (see below). Use —detach to submit and return
    immediately without following.
  • Ctrl+C (SIGINT) stops following only; the job keeps running.

Exit codes:
0 job COMPLETED, or detached submission accepted
1 job FAILED, or an unknown error
2 bad CLI input (e.g. unknown flag)
3 invalid argument (e.g. wrong number of arguments, script missing, or over the size limit)
5 job ERROR (infrastructure) or an internal CLI error
6 job CANCELLED, or interrupted with Ctrl+C
NOTE: the script’s numeric exit code is not propagated yet. A non-zero script
exit should surface as job FAILED and CLI exit 1, but not as the exact number.

Config file:
By default the command reads ./nebius.yaml when it exists. Use —run-config to
point to another file (distinct from the global —config, which selects the CLI
profile). CLI flags override values from YAML. Use —init to create a starter
nebius.yaml and .nebiusignore without submitting a job. Select hardware before
you run the generated configuration.

Artifacts:
By default the command creates or reuses a managed project bucket, mounts it at
/outputs with source path runs/{job-name}/, and exposes it to the script as NEBIUS_OUTPUT_DIR.
Use —output BUCKET_ID_OR_S3_URI to choose a bucket, or —no-output to
disable artifact storage.

Setup: Create a profile with ‘nebius profile create’. Set a platform and preset
via flags or nebius.yaml. These parameters have no defaults.
List Compute platforms and presets for your project:
nebius compute platform list —parent-id PROJECT_ID —all —format yaml
Choose hardware supported by Serverless in your project.
The project defaults from the active profile.
If —subnet-id is omitted, the backend uses the project’s default subnet in the workload region.
The backend provisions the runtime identity. Image, disk, and timeout have defaults (see the
flags below).
BETA: jobs only (no serving/endpoints), script directory ≤64 KiB gzip, and each
run provisions a fresh VM, so startup and teardown are part of the run cost.

​
Synopsis

​
Examples

​
Replace PLATFORM_NAME and PRESET_NAME with CPU hardware selected for your project.

nebius ai job run main.py —platform PLATFORM_NAME —preset PRESET_NAME

​
Pass arguments through to the script as sys.argv

nebius ai job run main.py —platform PLATFORM_NAME —preset PRESET_NAME — —epochs 10

​
Run on a GPU platform (pass a CUDA/ML image explicitly)

nebius ai job run main.py —platform gpu-h100-sxm —preset 1gpu-16vcpu-200gb —image nvcr.io/nvidia/pytorch:25.05-py3

​
With platform/preset in ./nebius.yaml, just:

nebius ai job run main.py —detach

​
Submit and return the Operation as JSON.

nebius ai job run main.py —detach —format json

​
Options

--detach (bool)

Submit the job and exit immediately without streaming logs or waiting for completion.

--disk-size (string)

Instance disk size, e.g. 250Gi (default 250Gi).

--dry-run (bool)

Validate the job request without creating or running a job.

--env (string array)

Set an environment variable, as KEY=VALUE. Repeatable.

--env-secret (string array)

Set an environment variable from a MysteryBox secret, as KEY=secret-id/key. Repeatable.

--image (string)

Container image to run the script in (default python:3.12-slim; pass a CUDA/ML image for gpu- platforms).

--init (bool)

Create starter nebius.yaml and .nebiusignore files, then exit without submitting a job.

--name (string)

Job name (default: ‘run-’ plus the script’s base name).

--no-output (bool)

Do not mount an output bucket or set NEBIUS_OUTPUT_DIR.

--output (string)

Output bucket to mount at /outputs and expose as NEBIUS_OUTPUT_DIR. Use ‘auto’ to create/reuse the managed project bucket, or pass a storage bucket ID/name or s3://bucket URI.

--parent-id (string)

Project ID to create the job in (default: the active profile’s project).

--platform (string)

Compute platform name for your project. Required; set —platform or platform: in nebius.yaml.

--preset (string)

Resource preset name for the selected platform. Required; set —preset or preset: in nebius.yaml.

--run-config (string)

Path to a YAML run config file (default: ./nebius.yaml when it exists). CLI flags override YAML. Distinct from the global —config, which selects the CLI profile.

--show-context (bool)

Dry run: print the files that would be packaged (and the compressed size) and exit, without submitting.

--subnet-id (string)

Subnet ID (default: the project’s default subnet in the workload region).

--timeout (duration: 2h30m10s)

Wall-clock cap for the job; the job is stopped past it (min 1h, max 168h).

--volume (string array)

Mount a volume, as RESOURCE_ID:MOUNT_PATH[:ro|rw], e.g. storagebucket-…:/outputs:rw. Repeatable.

​
Global Options

-h, --help (bool)

Show this message.

-p, --profile (string)

Set a profile for interacting with the cloud.

--format (string)

Output format. Supported values: yaml|json|jsonpath|table|text.

-f, --file (string)

Input file. For ‘update’ commands automatically set —full=true.

-c, --config (string)

Provide path to config file.

--debug (bool)

Enable debug logs.

-I, --impersonate-service-account-id (string)

Impersonate into the service account and use its token for a command.

--color (bool)

Enable colored output.

--no-browser (bool)

Do not open browser automatically on auth.

--insecure (bool)

Disable transport security.

--auth-timeout (duration: 2h30m10s)

Set the timeout for the request including authentication process, default is 15m0s.

--per-retry-timeout (duration: 2h30m10s)

Set the timeout for each retry attempt, default is 20s.

--retries (uint)

Set the number of retry attempts, 1 is disable retries, default is 3.

--no-check-update (bool)

Suppress check for updates.

--no-progress (bool)

Suppress progress indicators and spinners.

Auto generated on 14-Oct-2026