> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# nebius ai job run

<div>
  <h2>Name</h2>

  <p style={{ paddingLeft: "4ch" }}>
    <code>nebius ai job run</code>
  </p>

  <p style={{ paddingLeft: "7ch" }}>
    Package a local Python script and run it on a freshly provisioned Nebius VM as a<br />
    one-off Job, streaming the container logs to stdout and following the job to<br />
    completion.<br />

    <br />

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

    <br />

    Behavior for automation:<br />

    * stdout carries ONLY the job's container logs; job ID, status/progress,<br />
      artifact hints, and the BETA banner go to stderr, so stdout is safe to<br />
      capture or pipe.<br />
    * The command blocks until the job reaches a terminal state, then exits with a<br />
      code derived from that state (see below). Use --detach to submit and return<br />
      immediately without following.<br />
    * Ctrl+C (SIGINT) stops following only; the job keeps running.<br />
          <br />

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

    <br />

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

    <br />

    Artifacts:<br />
    By default the command creates or reuses a managed project bucket, mounts it at<br />
    /outputs with source path runs/{job-name}/, and exposes it to the script as NEBIUS\_OUTPUT\_DIR.<br />
    Use --output BUCKET\_ID\_OR\_S3\_URI to choose a bucket, or --no-output to<br />
    disable artifact storage.<br />

    <br />

    Setup: 'nebius auth login', plus a platform and preset (via flags or nebius.yaml)<br />
    — those two have no defaults. Project, subnet, and service account come from the<br />
    active profile; image, disk, and timeout have defaults (see the flags below).<br />
    BETA: jobs only (no serving/endpoints), script directory ≤64 KiB gzip, and each<br />
    run provisions a fresh VM, so startup and teardown are part of the run cost.
  </p>
</div>

<div>
  <h2>Synopsis</h2>

  <p style={{ paddingLeft: "4ch" }}>
    ```
    nebius ai job run [file.py] [-- args...]
      --detach
      --disk-size
      --env
      --env-secret
      --image
      --init
      --name
      --no-output
      --output
      --parent-id
      --platform
      --preset
      --run-config
      --show-context
      --subnet-id
      --timeout
      --volume
    ```
  </p>
</div>

<div>
  <h2>Examples</h2>

  <p style={{ paddingLeft: "4ch" }}>
    # Run a script and follow its logs to completion

    nebius ai job run main.py --platform cpu-e1 --preset 2vcpu-8gb

    # Pass arguments through to the script as sys.argv

    nebius ai job run main.py --platform cpu-e1 --preset 2vcpu-8gb -- --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
  </p>
</div>

<div>
  <h2>Options</h2>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--detach` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Submit the job and exit immediately without streaming logs or waiting for completion.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--disk-size` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Instance disk size, e.g. 250Gi (default 250Gi).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--env` (string array)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Set an environment variable, as KEY=VALUE. Repeatable.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--env-secret` (string array)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Set an environment variable from a MysteryBox secret, as KEY=secret-id/key. Repeatable.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--image` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Container image to run the script in (default python:3.12-slim; pass a CUDA/ML image for gpu- platforms).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--init` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Create starter nebius.yaml and .nebiusignore files, then exit without submitting a job.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--name` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Job name (default: 'run-' plus the script's base name).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--no-output` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Do not mount an output bucket or set NEBIUS\_OUTPUT\_DIR.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--output` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      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.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--parent-id` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Project ID to create the job in (default: the active profile's project).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--platform` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Full compute platform name, e.g. cpu-e1 or gpu-h100-sxm (required; or set platform: in nebius.yaml).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--preset` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Resource preset, e.g. 2vcpu-8gb (required; or set preset: in nebius.yaml).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--run-config` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      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.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--show-context` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Dry run: print the files that would be packaged (and the compressed size) and exit, without submitting.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--subnet-id` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Subnet ID for the instance (default: resolved from the project).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--timeout` (duration: 2h30m10s)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Wall-clock cap for the job; the job is stopped past it (min 1h, max 168h).
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--volume` (string array)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Mount a volume, as RESOURCE\_ID:MOUNT\_PATH\[:ro|rw], e.g. storagebucket-...:/outputs:rw. Repeatable.
    </p>
  </div>
</div>

<div>
  <h2>Global Options</h2>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `-h, --help` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Show this message.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `-p, --profile` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Set a profile for interacting with the cloud.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--format` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Output format. Supported values: yaml|json|jsonpath|table|text.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `-f, --file` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Input file. For 'update' commands automatically set --full=true.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `-c, --config` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Provide path to config file.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--debug` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Enable debug logs.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `-I, --impersonate-service-account-id` (string)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Impersonate into the service account and use its token for a command.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--color` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Enable colored output.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--no-browser` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Do not open browser automatically on auth.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--insecure` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Disable transport security.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--auth-timeout` (duration: 2h30m10s)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Set the timeout for the request including authentication process, default is 15m0s.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--per-retry-timeout` (duration: 2h30m10s)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Set the timeout for each retry attempt, default is 20s.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--retries` (uint)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Set the number of retry attempts, 1 is disable retries, default is 3.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--no-check-update` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Suppress check for updates.
    </p>
  </div>

  <div style={{ paddingLeft: "4ch" }}>
    <p>
      `--no-progress` (bool)
    </p>

    <p style={{ paddingLeft: "4ch" }}>
      Suppress progress indicators and spinners.
    </p>
  </div>
</div>

*Auto generated on 16-Jul-2026*