flyte-migrate

Migrate FlyteKit v1 workflows to Flyte v2 — without changing a single line of code.

What is flyte-migrate?

flyte-migrate is a zero-effort compatibility layer that lets your existing FlyteKit v1 workflows run on Flyte v2 infrastructure. No rewrites, no refactoring — just add one import and deploy.

+ import flyte_migrate
  from flytekit import task, workflow

  @task(cache=True, retries=3)
  def greet(name: str) -> str:
      return f"Hello, {name}!"

  @workflow
  def hello_wf(name: str) -> str:
      return greet(name=name)

That's it. Your v1 workflow now runs on Flyte v2.

Why flyte-migrate?

Quick Start

Install

pip install flyte-migrate

Add one line to your v1 code

import flyte_migrate  # noqa: F401, I001  <-- add this as the first import

Run on Flyte v2

import flyte_migrate  # noqa: F401, I001
import logging
from flytekit import task, workflow, ImageSpec

image = ImageSpec(packages=["pandas"])

@task(container_image=image, cache=True, retries=3)
def process(data: str) -> str:
    return data.upper()

@workflow
def my_workflow(data: str) -> str:
    return process(data=data)

if __name__ == "__main__":
    import flyte

    flyte.init_from_config(log_level=logging.DEBUG)
    run = flyte.with_runcontext(mode="remote").run(my_workflow, data="hello")
    print(run.url)

Or use the CLI

Installing flyte-migrate also gives you pyflyte-migrate, which mirrors the pyflyte UX against a v2 cluster. Files driven by the CLI don't need the import flyte_migrate line — the shim is applied automatically before your file is loaded.

# Run locally (pyflyte semantics: local by default)
pyflyte-migrate run wf.py my_workflow --data=hello

# Run on the v2 cluster
pyflyte-migrate run --remote -p my-project -d development wf.py my_workflow --data=hello

# Register (deploy) workflows from files or directories
pyflyte-migrate register -p my-project -d development workflows/

Cluster connection uses the standard v2 config discovery (./config.yaml, .flyte/config.yaml, ~/.flyte/config.yaml, ...), overridable with -c /path/to/config.yaml or a FLYTE_API_KEY environment variable. Note: register loads all files into one shared environment, so function names must be unique across the registered files.

What Gets Translated

flyte-migrate intercepts v1 API calls at import time and translates them to v2 equivalents. Here's what's covered:

Core APIs

Task Parameters

All commonly used @task parameters are translated:

ImageSpec

All ImageSpec fields are translated, including:

• packages (with automatic v1 → v2 plugin name mapping)
• apt_packages, pip_index, pip_extra_index_url, pip_extra_args
• base_image (string or nested ImageSpec)
• python_version, registry, platform
• env, commands, requirements, copy, source_root
• pip_secret_mounts → flyte.Secret objects

Plugin package names are automatically translated:

flytekitplugins-spark    → flyteplugins-spark
flytekitplugins-ray      → flyteplugins-ray
flytekitplugins-dask     → flyteplugins-dask
flytekitplugins-kfpytorch → flyteplugins-pytorch

Plugins

Data Types

All v1 type patterns work transparently through the shim:

• Primitives: int, float, str, bool, datetime
• Collections: List[T], Dict[K, V], Tuple[T, ...], Optional[T]
• Structured: NamedTuple, @dataclass, Enum
• Flyte types: FlyteFile, FlyteDirectory, StructuredDataset
• Annotated types: typing.Annotated[T, ...]

Architecture

┌─────────────────────────────────────┐
│         Your v1 Code                │
│  @task, @workflow, ImageSpec, ...   │
└──────────────┬──────────────────────┘
               │  import flyte_migrate
               ▼
┌─────────────────────────────────────┐
│         flyte-migrate shim          │
│                                     │
│  _task.py      → @task decorator    │
│  _workflow.py  → @workflow decorator│
│  _dynamic.py   → @dynamic decorator│
│  _map.py       → map_task()        │
│  _launchplan.py→ LaunchPlan        │
│  _reference.py → @reference_task   │
│  _image.py     → ImageSpec→Image   │
│  _resource.py  → Resources merge   │
│  _secret.py    → Secret transform  │
│  _pod_template.py → PodTemplate    │
│  _deck.py      → Deck→Report      │
│  _context.py   → ExecutionParams   │
│  _plugins/     → Spark,Ray,Dask,...│
└──────────────┬──────────────────────┘
               │  translated v2 calls
               ▼
┌─────────────────────────────────────┐
│         Flyte v2 SDK                │
│  TaskEnvironment, Image, Resources  │
└─────────────────────────────────────┘

Known Limitations

Some v1 features have no v2 equivalent and are handled gracefully:

Examples

The examples/ directory contains runnable examples for every feature:

Development

# Clone and install
git clone https://github.com/flyteorg/flyte-migrate.git
cd flyte-migrate
uv sync

# Format, lint, test
make fmt
make lint
uv run pytest

# Run a single test
uv run pytest tests/test_transform_utils.py -v

FAQ

Do I need to change my v1 code? No. Add import flyte_migrate as the first import — everything else stays the same.

What if I use plugins like Spark or Ray? They work. Plugin configs (spark_conf, worker nodes, etc.) are automatically translated to v2 equivalents. Plugin pip packages are also renamed automatically.

Is there a performance overhead? The translation happens once at import time. At runtime, your tasks execute directly on v2 infrastructure with no overhead.

Can I mix v1 and v2 code? Yes. You can gradually introduce native v2 code while keeping v1 code working through flyte-migrate.

What Python versions are supported? Python 3.10+.

License

Apache License 2.0 — see LICENSE for details.