Deploy command options

The flyte deploy command provides extensive configuration options:

flyte deploy [OPTIONS] <PATH> [TASK_ENV_VARIABLE]

--project, --domain

flyte deploy --domain <DOMAIN> --project <PROJECT> <SOURCE_FILE> <TASK_ENV_VARIABLE>

You can specify --project and --domain which will override any defaults defined in your config.yaml:

# Use defaults from default config.yaml
flyte deploy my_example.py env

# Specify target project and domain
flyte deploy --project my-project --domain development my_example.py env

--version

flyte deploy --version <VERSION> <SOURCE_FILE> <TASK_ENV_VARIABLE>

The --version option controls how deployed tasks are tagged and identified in the Flyte backend:

# Auto-generated version (default)
flyte deploy my_example.py env

# Explicit version
flyte deploy --version v1.0.0 my_example.py env

# Required when using copy-style none (no code bundle to generate hash from)
flyte deploy --copy-style none --version v1.0.0 my_example.py env

When versions are used

• Explicit versioning: Provides human-readable task identification (e.g., v1.0.0, prod-2024-12-01)
• Auto-generated versions: When no version is specified, Flyte creates an MD5 hash from the code bundle, environment configuration, and image cache
• Version requirement: copy-style none mandates explicit versions since there’s no code bundle to hash
• Task referencing: Versions enable precise task references in flyte run deployed-task and workflow invocations

--dry-run

flyte deploy --dry-run <SOURCE_FILE> <TASK_ENV_VARIABLE>

The --dry-run option allows you to preview what would be deployed without actually performing the deployment:

# Preview what would be deployed
flyte deploy --dry-run my_example.py env

--all and --recursive

flyte deploy --all <SOURCE_FILE>

flyte deploy --recursive <DIRECTORY_PATH>

Control which environments get discovered and deployed:

Single environment (default):

# Deploy specific environment variable
flyte deploy my_example.py env

All environments in file:

# Deploy all TaskEnvironment objects in file
flyte deploy --all my_example.py

Recursive directory deployment:

# Deploy all environments in directory tree
flyte deploy --recursive ./src

# Combine with comprehensive bundling
flyte deploy --recursive --copy-style all ./project

--copy-style

flyte deploy --copy_style [loaded_modules|all|none] <SOURCE_FILE> <TASK_ENV_VARIABLE>

The --copy-style option controls what gets packaged:

--copy-style loaded_modules (default)

flyte deploy --copy-style loaded_modules my_example.py env

• Includes: Only imported Python modules from your project
• Excludes: Site-packages, system modules, Flyte SDK
• Best for: Most projects (optimal size and speed)

--copy-style all

flyte deploy --copy-style all my_example.py env

• Includes: All files in project directory
• Best for: Projects with dynamic imports or data files

--copy-style none

flyte deploy --copy-style none --version v1.0.0 my_example.py env

• Requires: Explicit version parameter
• Best for: Pre-built container images with baked-in code

--root-dir

flyte deploy --root-dir <DIRECTORY> <SOURCE_FILE> <TASK_ENV_VARIABLE>

The --root-dir option overrides the default source directory that Flyte uses as the base for code bundling and import resolution. This is particularly useful for monorepos and projects with complex directory structures.

Default behavior (without --root-dir)

• Flyte uses the current working directory as the root
• Code bundling starts from this directory
• Import paths are resolved relative to this location

Common use cases

Monorepos:

# Deploy service from monorepo root
flyte deploy --root-dir ./services/ml ./services/ml/my_example.py env

# Deploy from anywhere in the monorepo
cd ./docs/
flyte deploy --root-dir ../services/ml ../services/ml/my_example.py env

Cross-directory imports:

# When workflow imports modules from sibling directories
# Project structure: project/workflows/my_example.py imports project/src/utils.py
cd project/workflows/
flyte deploy --root-dir .. my_example.py env  # Sets root to project/

Working directory independence:

# Deploy from any location while maintaining consistent bundling
flyte deploy --root-dir /path/to/project /path/to/project/my_example.py env

How it works

1. Code bundling: Files are collected starting from --root-dir instead of the current working directory
2. Import resolution: Python imports are resolved relative to the specified root directory
3. Path consistency: Ensures the same directory structure in local and remote execution environments
4. Dependency packaging: Captures all necessary modules that may be located outside the workflow file’s immediate directory

Example with complex project structure

my-project/
├── services/
│   ├── ml/
│   │   └── my_example.py     # imports shared.utils
│   └── api/
└── shared/
    └── utils.py

# Deploy ML service workflows with access to shared utilities
flyte deploy --root-dir ./my-project ./my-project/services/ml/my_example.py env

This ensures that both services/ml/ and shared/ directories are included in the code bundle, allowing the workflow to successfully import shared.utils during remote execution.

--image

flyte deploy --image <IMAGE_MAPPING> <SOURCE_FILE> <TASK_ENV_VARIABLE>

The --image option allows you to override image URIs at deployment time without modifying your code. Format: imagename=imageuri

Named image mappings

# Map specific image reference to URI
flyte deploy --image base=ghcr.io/org/base:v1.0 my_example.py env

# Multiple named image mappings
flyte deploy \
  --image base=ghcr.io/org/base:v1.0 \
  --image gpu=ghcr.io/org/gpu:v2.0 \
  my_example.py env

Default image mapping

# Override default image (used when no specific image is set)
flyte deploy --image ghcr.io/org/default:latest my_example.py env

How it works

• Named mappings (e.g., base=URI) override images created with Image.from_ref_name("base").
• Unnamed mappings (e.g., just URI) override the default “auto” image.
• Multiple --image flags can be specified.
• Mappings are resolved during the image building phase of deployment.

--ignore-load-errors

flyte deploy --ignore-load-errors <SOURCE_PATH> <TASK_ENV_VARIABLE>

The --ignore-load-errors option allows the deployment process to continue even if some modules fail to load during the environment discovery phase. This is particularly useful for large projects or monorepos where certain modules may have missing dependencies or other issues that prevent them from being imported successfully.

# Continue deployment despite module failures
flyte deploy --recursive --ignore-load-errors ./large-project

--no-sync-local-sys-paths

flyte deploy --no-sync-local-sys-paths <SOURCE_FILE> <TASK_ENV_VARIABLE>

The --no-sync-local-sys-paths option disables the automatic synchronization of local sys.path entries to the remote container environment. This is an advanced option for specific deployment scenarios.

Default behavior (path synchronization enabled)

• Flyte captures local sys.path entries that are under the root directory
• These paths are passed to the remote container via the _F_SYS_PATH environment variable
• At runtime, the remote container adds these paths to its sys.path, maintaining the same import environment

When to disable path synchronization

# Disable local sys.path sync (advanced use case)
flyte deploy --no-sync-local-sys-paths my_example.py env

Use cases for disabling

• Custom container images: When your container already has the correct sys.path configuration
• Conflicting path structures: When local development paths would interfere with container paths
• Security concerns: When you don’t want to expose local development directory structures
• Minimal environments: When you want precise control over what gets added to the container’s Python path

How it works

• Enabled (default): Local paths like ./my_project/utils get synchronized and added to remote sys.path
• Disabled: Only the container’s native sys.path is used, along with the deployed code bundle

Most users should leave path synchronization enabled unless they have specific requirements for container path isolation or are using pre-configured container environments.

SDK deployment options

The core deployment functionality is available programmatically through the flyte.deploy() function, though some CLI-specific options are not applicable:

import flyte

env = flyte.TaskEnvironment(name="my_env")

@env.task
async def process_data(data: str) -> str:
    return f"Processed: {data}"

if __name__ == "__main__":
    flyte.init_from_config()

    # Comprehensive deployment configuration
    deployment = flyte.deploy(
        env,                          # Environment to deploy
        dryrun=False,                 # Set to True for dry run
        version="v1.2.0",             # Explicit version tag
        copy_style="loaded_modules"   # Code bundling strategy
    )
    print(f"Deployment successful: {deployment[0].summary_repr()}")