Skip to content

dstack run

This command runs a given configuration.


$ dstack run --help
                  [-e ENV ...]
                  [-p PORT ...]
                  [--gpu GPU] [--memory MEMORY] [--shm-size SHM_SIZE]
                  [--spot-auto | --spot | --on-demand] 
                  [--no-retry | --retry-limit RETRY]
                  [--max-price MAX_PRICE]
                  [--backend BACKEND_TYPE ...]
                  [--profile PROFILE_NAME] [--project PROJECT_NAME]
                  [ARGS ...]

When running dev environments or tasks, dstack uses the exact version of code that is present in the folder where you use the dstack run command.

If your folder has large files or folders, this may affect the performance of the dstack run command. To avoid this, make sure to create a .gitignore file and include these large files or folders that you don't want to include when running dev environments or tasks.

Arguments reference


  • WORKING_DIR – (Required) The working directory of the run. Example: dstack run .
  • -f CONFIGURATION_FILE, --file CONFIGURATION_FILE – (Optional) The configuration file to run. If not specified, dstack will use the WORKING_DIR/.dstack.yml configuration by default. Example: dstack run . -f llama-2/serve.dstack.yml
  • -n RUN_NAME, --name RUN_NAME – (Optional) The name of the run. If not specified, dstack will pick a random name. Example: dstack run . -n my-dev-environment
  • -e ENV, --env ENV – (Optional) Set environment variables. Example: dstack run . -e MYVAR1=foo -e MYVAR2=bar
  • -p PORT, --port PORT – (Optional) Configure port forwarding. Examples: dstack run . -p 8000 (forwards the 8000 port of the task to the same port on your local machine) or dstack run . -p 8001:8000 (forwards the 8000 port of the task to the 8001 port on your local machine).
  • -y, --yes - (Optional) Do not ask a confirmation
  • -p PROFILE, --profile PROFILE – (Optional) The name of the profile
  • -p PROJECT, --project PROJECT – (Optional) The name of the project
  • -d, --detach – (Optional) Run in the detached mode (no logs are shown in the output, and the command doesn't wait until the run is finished)


  • --gpu GPU – (Optional) Request GPU. Examples: dstack run . --gpu A10 or dstack run . --gpu 24B or dstack run . --gpu A100:8
  • --memory MEMORY – (Optional) The minimum size of memory. Examples: dstack run . --memory 64GB
  • --shm_size SHM_SIZE – (Optional) The size of shared memory. Required to set if you are using parallel communicating processes. Example: dstack run . --shm_size 8GB
  • --max_price MAX_PRICE – (Optional) The maximum price per hour, in dollars. Example: dstack run . --max-price 1.1
  • -backend BACKEND – (Optional) Force using listed backends only. Possible values: aws, azure, gcp, lambda. If not specified, all configured backends are tried. Example: dstack run . --backend aws --backend gcp
  • --spot – (Optional) Force using spot instances only. Example: dstack run . --spot
  • --spot-auto – (Optional) Force using spot instances if they are available and on-demand instances otherwise. This is the default for tasks and services. Example: dstack run . --spot-auto
  • --on-demand – (Optional) Force using on-demand instances. This is the default for dev environments. Example: dstack run . --on-demand
  • --no-retry – (Optional) Do not wait for capacity. This is the default. Example: dstack run . --no-retry
  • --retry-limit RETRY_LIMIT – (Optional) The duration to wait for capacity. Example: dstack run . --retry-limit 3h or dstack run . --retry-limit 2d
  • --max-duration MAX_DURATION – (Optional) The maximum duration of a run. After it elapses, the run is forced to stop. Protects from running idle instances. Defaults to 6h for dev environments and to 72h for tasks. Examples: dstack run . --max-duration 3h or dstack run . --max-duration 2d or dstack run . --max-duration off.



  • --build – Pre-build the environment (if you're using the build property in dstack.yml) if it's not pre-built yet. Example: dstack run . --build
  • --force-build – Force pre-building the environment (if you're using the build property in dstack.yml, even if it has been pre-built before. Example: dstack run . --force-build
  • --reload – (Optional) Enable auto-reloading of your local changes into the running task. Maybe be used together with Streamlit, Fast API, Gradio for auto-reloading local changes. Example: dstack run . --reload
  • --max-offers MAX_OFFERS – (Optional) Set the maximum number of offers shown before the confirmation.