Local setup

This guide covers setting up your local development environment and configuring the flyte CLI and SDK to connect to your Union/Flyte instance.

Prerequisites

  • Python 3.10+
  • uv — A fast Python package installer. See the uv installation guide.
  • Access to a Union/Flyte instance (URL and a project where you can run workflows)

Install the flyte package

Create a virtual environment and install the flyte package:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install --prerelease=allow flyte

Verify installation:

flyte --version

Configuration file

As we did in Quickstart, use flyte create config to create a configuration file:

flyte create config \
    --endpoint my-org.my-company.com \
    --domain development \
    --project my-project \
    --builder remote

This creates ./.flyte/config.yaml:

admin:
  endpoint: dns:///my-org.my-company.com
image:
  builder: remote
task:
  org: my-org
  domain: development
  project: my-project

Create a custom config file with all available options:

flyte create config \
    --endpoint my-org.my-company.com \
    --org my-org \
    --domain development \
    --project my-project \
    --builder remote \
    --insecure \
    --output my-config.yaml \
    --force
See the CLI reference for all parameters.

admin — Connection details for your Union/Flyte instance.

  • endpoint: URL with dns:/// prefix. If your UI is at https://my-org.my-company.com, use dns:///my-org.my-company.com.
  • insecure: Set to true only for local instances without TLS.

image — Docker image building configuration.

  • builder: How container images are built.
    • remote (Union): Images built on Union’s infrastructure.
    • local (Flyte OSS): Images built on your machine. Requires Docker. See Image building.

task — Default settings for task execution.

  • org: Organization name (usually matches the first part of your endpoint URL).
  • domain: Environment separation (development, staging, production).
  • project: Default project for deployments. Must already exist on your instance.

Using the configuration

You can reference your config file explicitly or let the SDK find it automatically.

Explicit configuration

CLI: Use --config or -c:

flyte --config my-config.yaml run hello.py main
flyte -c my-config.yaml run hello.py main

Python: Initialize with flyte.init_from_config:

flyte.init_from_config("my-config.yaml")
run = flyte.run(main)

Without an explicit path, the SDK searches these locations in order:

  1. ./config.yaml
  2. ./.flyte/config.yaml
  3. UCTL_CONFIG environment variable
  4. FLYTECTL_CONFIG environment variable
  5. ~/.union/config.yaml
  6. ~/.flyte/config.yaml

CLI:

flyte run hello.py main

Python:

Check current configuration 

flyte get config

Output shows the active configuration:

CLIConfig(
    Config(
        platform=PlatformConfig(endpoint='dns:///my-org.my-company.com', scopes=[]),
        task=TaskConfig(org='my-org', project='my-project', domain='development'),
        source=PosixPath('/Users/me/.flyte/config.yaml')
    ),
    ...
)

Inline configuration

Skip the config file entirely by passing parameters directly.

CLI

Some parameters go after flyte, others after the subcommand:

flyte \
    --endpoint my-org.my-company.com \
    --org my-org \
    run \
    --domain development \
    --project my-project \
    hello.py \
    main

See the CLI reference for details.

Python

Use flyte.init:

flyte.init(
    endpoint="dns:///my-org.my-company.com",
    org="my-org",
    project="my-project",
    domain="development",
)

See related methods:

Next steps

With your environment fully configured, you’re ready to build:

  • Flyte basics: Understand TaskEnvironments, tasks, runs, and actions through working examples.