Install & Compatibility
Where this runs
tested against v0.3.7 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 274.1MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 23.5s · import 0.000s · 275MB
272MB installed
● package 272MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
DaskTaskRunner
✓ from prefect_dask import DaskTaskRunner
✗ from prefect_dask.runners import DaskTaskRunner
This quickstart defines a simple Prefect flow that uses `DaskTaskRunner` to execute tasks. If the `DASK_SCHEDULER_ADDRESS` environment variable is not set, it automatically spins up a local Dask cluster. Otherwise, it attempts to connect to the specified Dask scheduler address, demonstrating how to use Dask locally or with an existing distributed setup.
import os
from prefect import flow, task
from prefect_dask.runners import DaskTaskRunner
@task
def my_dask_task(x):
print(f"Executing task on Dask: {x}")
return x * 2
@flow(task_runner=DaskTaskRunner(address=os.environ.get("DASK_SCHEDULER_ADDRESS", None)))
def my_dask_flow(num: int):
"""A Prefect flow that runs tasks on a Dask cluster."""
# If DASK_SCHEDULER_ADDRESS is not set, a local Dask cluster will be created.
# Otherwise, it attempts to connect to the specified Dask scheduler address.
future = my_dask_task.submit(num)
result = future.result()
print(f"Task result: {result}")
return result
if __name__ == "__main__":
# Example 1: Run with a local Dask cluster (default if DASK_SCHEDULER_ADDRESS not set)
print("\n--- Running flow with local Dask cluster ---")
output_local = my_dask_flow(5)
print(f"Flow with local Dask completed, output: {output_local}")
# Example 2: Run by attempting to connect to an external Dask scheduler
# Uncomment and set DASK_SCHEDULER_ADDRESS to test with a remote scheduler
# os.environ["DASK_SCHEDULER_ADDRESS"] = "tcp://127.0.0.1:8786"
# print("\n--- Running flow with external Dask cluster (if configured) ---")
# output_remote = my_dask_flow(10)
# print(f"Flow with external Dask completed, output: {output_remote}")
# Clean up environment variable if set for example
# if "DASK_SCHEDULER_ADDRESS" in os.environ:
# del os.environ["DASK_SCHEDULER_ADDRESS"]
Debug
Known issues
breakingPrefect 1.x Dask Executor (`DaskExecutor`) is incompatible with Prefect 2.x and `prefect-dask`. The new approach uses `DaskTaskRunner`.fixRewrite flows to use `DaskTaskRunner` as the `task_runner` for your flow, replacing `DaskExecutor` usage. Consult Prefect 2.x migration guides.
affects: Prefect 1.x users migrating to Prefect 2.x
gotchaIncorrect or unresolvable Dask scheduler address can lead to unexpected behavior or errors. If `address` is `None` (default), a local Dask cluster is created, which might not be intended for production deployments.fixAlways explicitly configure the `address` for `DaskTaskRunner` when connecting to an existing distributed Dask cluster. Ensure the Dask scheduler is running and accessible at the specified address. For local development, `address=None` is often sufficient.
affects: All versions of prefect-dask
gotchaDask and Distributed library version mismatches can cause subtle runtime errors or unexpected behavior within the Dask cluster.fixEnsure `dask` and `distributed` are installed with compatible versions. Check the `prefect-dask` documentation or Dask documentation for recommended version pairings. It's often best to install them together or upgrade them simultaneously.
affects: All versions
gotchaSerialization issues with custom objects or complex data structures when passing them to Dask tasks. Dask uses `cloudpickle` by default, but complex types might still cause problems.fixEnsure custom classes are pickleable. If passing large data, consider using Dask's distributed collections (e.g., Dask DataFrames, Bags) or storing data in a shared, accessible location (e.g., S3, local disk) and passing paths instead of raw objects.
affects: All versions
Upgrade
Version history
0.3.7latest on PyPI · released Jun 5, 2026
Audit
Dependencies
prefectrequiredCore Prefect orchestration library (version 2.x required).
daskrequiredDistributed computing framework.
distributedrequiredDask's distributed scheduler and workers library.