Skip to main content

Getting Started

Prerequisites​

  • Python 3.10 or newer. The package declares requires-python = ">=3.10".
  • uv for the recommended environment and dependency workflow.
  • No additional system dependencies are declared for installing or running the SDK locally.
  • A Docker daemon is required when working from a checkout and running make dist: the contributor setup builds a wheel so the default Image() can use local changes.
  • A Flyte endpoint and credentials are only needed for remote runs, deployment, and serving. Local task execution does not require a backend.

Flyte is a Python SDK for authoring tasks, workflows, compound AI applications, and services. Its public authoring API is exposed from flyte and flyte.app; underscore-prefixed modules are implementation details.

Installation​

From the repository with uv​

The repository's documented development setup is:

uv sync
make dist

uv sync creates or updates the project environment from uv.lock. make dist cleans prior build output and builds the Flyte wheel with uv; it requires Docker because the resulting distribution is used by the default image-building workflow.

Add Flyte to an existing uv project​

For an application that consumes the published package rather than modifying this checkout:

uv add flyte

Install the optional TUI when you want the rich local development interface:

uv add 'flyte[tui]'

Other declared extras are aiosqlite, connector, examples-test, and sandbox. Add only the extra needed by the feature you use.

Hello World / Quick Start​

Create hello.py with a task environment and a typed task:

import flyte

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

@env.task
def greet(name: str) -> str:
    return f"Hello, {name}!"

if __name__ == "__main__":
    result = flyte.run(greet, name="world")
    print(result.outputs()[0])

TaskEnvironment.task turns the function into a Flyte task template. Calling the task directly is also supported for ordinary local unit tests; flyte.run executes the task through Flyte's run machinery. The local run path is useful for trying the SDK without configuring a backend.

Run the file with the environment managed by uv:

uv run python hello.py

You can also invoke a task declared with @env.task through the CLI. The CLI accepts the Python file, the task name, and then task arguments:

uv run flyte run --local hello.py greet --name world

For remote execution, initialize the SDK before calling flyte.run:

import flyte

flyte.init_from_config()
run = flyte.run(greet, name="world")
print(run.url)

init_from_config() loads the automatically discovered configuration unless a path or configuration object is supplied. The top-level flyte CLI exposes task execution, serving, build, deploy, object management, and documentation-generation commands.

Configuration​

Backend configuration​

Remote SDK calls require either an endpoint or an API key. The general initializer is flyte.init(...); the convenience initializer flyte.init_from_config() reads the default configuration or a supplied path. The CLI likewise discovers its default configuration and supports an explicit file with --config.

For API-key authentication, set FLYTE_API_KEY or pass the encoded key to flyte.init_from_api_key():

import flyte

flyte.init_from_api_key(
    project="my-project",
    domain="development",
)

The SDK expects this API key to contain the endpoint, client ID, client secret, and organization information. Do not commit it to source control.

The CLI also supports persistent connection overrides such as --endpoint, --insecure, --auth-type, --org, and --config. Use flyte --help or flyte run --help to see the options available in the installed version.

Images and optional dependencies​

An environment can specify an image using the public flyte.Image API. Images use a constructor followed by fluent customization methods:

import flyte

env = flyte.TaskEnvironment(
    name="data_task",
    image=(
        flyte.Image.from_debian_base(python_version=(3, 12))
        .with_pip_packages("pandas")
    ),
)

Image construction and remote execution may require Docker or a configured remote image builder, depending on the selected workflow. The CLI can override image mappings with --image without changing the task file.

Verify Installation​

Confirm that the package imports and reports its installed version:

uv run python -c "import flyte; print(flyte.version())"

Run the repository's non-integration, non-sandbox test suite:

uv run python -m pytest -k "not integration and not sandbox" tests

For a focused local CLI check, the repository's CLI tests exercise flyte run --local against task files. You can inspect the installed command surface with:

uv run flyte --help

Other Install Options​

pip​

The README documents the published-package installation with pip:

pip install flyte

For the optional TUI:

pip install 'flyte[tui]'

Use a virtual environment when installing with pip so the SDK and its optional dependencies remain isolated.

Source checkout​

The source checkout is installed and built through the uv workflow shown in the repository contribution setup: uv sync followed by make dist. This path is intended for changing Flyte itself or testing local package and image changes, and make dist requires a Docker daemon.

Next Steps​

  • Explore the Tasks and Environments model built around TaskEnvironment and @env.task.
  • Learn about Run Tasks Locally, Remotely, and in Hybrid Mode before connecting runs to a backend.
  • For serving HTTP applications, see the Serving Applications patterns using flyte.app.AppEnvironment or flyte.app.extras.FastAPIAppEnvironment.
  • Browse the repository's examples/ directory for tasks, apps, sandbox execution, storage, triggers, and type transformers.
  • Use the flyte.cli for run, serve, deploy, build, and management commands.

Troubleshooting​

flyte.init_from_api_key() reports a missing API key​

Pass api_key= explicitly or set FLYTE_API_KEY in the process environment. The initializer raises an initialization error when neither is present.

init_from_config() cannot find a configuration file​

Call flyte.init_from_config(path_or_config=...) with an existing configuration path, or provide the endpoint/API-key settings through the supported initialization methods. The CLI has the analogous --config path option.

Image builds fail or local changes are not included​

Ensure Docker is running. In a source checkout, rerun make dist after uv sync; the repository documents this build step specifically so the default image can use local changes.

FastAPI app setup reports a missing dependency​

FastAPIAppEnvironment checks for both fastapi and uvicorn and raises an explanatory ModuleNotFoundError if either is absent. Install the corresponding packages (or use the project dependency setup) before constructing the environment.

A task does not run through the CLI​

Put task arguments after the task name, for example flyte run --local hello.py greet --name world. The CLI treats the file and task name as the target and parses subsequent options as that task's inputs. Use flyte run --help for the complete syntax.