Install & Compatibility
Where this runs
tested against v2026.8.0 · 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.910 runs
installs and imports cleanly · install 0.0s · import 1.460s · 50.5MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 5.0s · import 1.366s · 52MB
53MB installed
● package 53MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from distributed import Client
✗ from dask.distributed import Client
While `dask.distributed` is a valid module, `distributed` is the top-level package and preferred import path for its core components.
LocalCluster
✓ from distributed import LocalCluster
fire_and_forget
✓ from distributed import fire_and_forget
This quickstart demonstrates how to set up a local Dask cluster using `LocalCluster` and connect a `Client` to it. It then submits a simple `inc` function for parallel execution and gathers the results. The use of context managers (`with`) is crucial for proper resource management and cleanup. A dashboard link is printed if `bokeh` is installed.
from distributed import Client, LocalCluster
import time
def inc(x):
time.sleep(0.1) # Simulate work
return x + 1
# Start a local Dask cluster
# Using 'with' statement ensures proper cleanup
with LocalCluster(n_workers=2, threads_per_worker=2, dashboard_address=':8787') as cluster:
print(f"Dashboard available at: {cluster.dashboard_link}")
# Connect a client to the cluster
with Client(cluster) as client:
print(f"Client connected to: {client.scheduler.address}")
# Submit tasks
futures = client.map(inc, range(10))
# Gather results
results = client.gather(futures)
print(f"Results: {results}")
assert results == [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
print("Client disconnected.")
print("LocalCluster closed.")
dask-scheduler --version
Debug
Known issues
breakingStarting with version 2026.1.2, `distributed` requires `pyarrow>=16`. Older versions of `pyarrow` may lead to `ImportError` or serialization issues, especially with Dask DataFrames.fixUpgrade `pyarrow` to version 16 or newer: `pip install 'pyarrow>=16'`.
affects: 2026.1.2+
breaking`distributed` now requires Python 3.10 or newer. Support for Python 3.9 and older has been dropped.fixEnsure your Python environment is version 3.10 or greater. Upgrade Python or use a compatible environment.
affects: 2025.12.0+
breakingStarting with version 2025.12.0, `distributed` requires `toolz>=0.12.0`. Older versions may cause compatibility errors.fixUpgrade `toolz` to version 0.12.0 or newer: `pip install 'toolz>=0.12.0'`.
affects: 2025.12.0+
gotchaThe Dask diagnostics dashboard requires `bokeh` to be installed. Without it, the dashboard link will still be provided but will not function correctly, often leading to a blank page or errors.fixInstall `distributed` with the `[dashboard]` or `[complete]` extra: `pip install "distributed[dashboard]"`.
affects: All versions
gotchaWhen using `Client` or `LocalCluster`, always use them as context managers (`with Client(...) as client:`) or explicitly call their `.close()` methods to ensure proper cleanup of resources, especially in scripts or long-running applications. Failing to do so can leave orphaned processes or open ports.fixWrap `Client` and `LocalCluster` instantiation in `with` statements: `with LocalCluster(...) as cluster: ... with Client(cluster) as client: ...`.
affects: All versions
breaking`distributed` might not yet be fully compatible with Python 3.13. Running on this unverified Python version can lead to unexpected behavior, including process timeouts or failures during initialization. Please check `distributed`'s official documentation for current Python compatibility.fixUse a currently supported Python version (e.g., 3.10-3.12) or await an official `distributed` release with Python 3.13 compatibility.
affects: All versions (until Python 3.13 is officially supported)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'distributed'
The 'distributed' library, which is part of Dask, is not installed or is not accessible in the Python environment where the code is being executed. This can also occur due to an inactive virtual environment or incorrect PYTHONPATH settings.
fixInstall the 'distributed' library using pip (`pip install distributed`) or conda (`conda install distributed`). If using a virtual environment, ensure it is activated before running your script.
ConnectionRefusedError: [Errno 111] Connection refused
The Dask client is unable to establish a connection with the Dask scheduler. This commonly happens if the scheduler is not running, is configured with an incorrect host or port, or if a firewall is blocking the connection between the client and the scheduler.
fixVerify that the Dask scheduler is running and that its address (host and port) matches what the client is trying to connect to. Check firewall configurations or security groups if the scheduler is on a remote machine.
distributed.worker - WARNING - Worker exceeded 95% memory budget. Restarting...
A Dask worker has consumed nearly all of its allocated memory, leading the Dask Nanny process to automatically restart it to prevent system instability. This usually indicates that tasks are too memory-intensive for the worker's current configuration or that there's a memory leak in the user's code.
fixReduce the memory footprint of your tasks, increase the 'memory_limit' parameter when initializing your Dask client or workers (e.g., `Client(memory_limit='8GB')`), or decrease the number of workers to allocate more memory to each.
CancelledError
A Dask future or task was explicitly cancelled, timed out, or implicitly cancelled due to a failure or disconnection of a scheduler or worker it depended on. In cloud deployments, an 'idle timeout' on the scheduler can also trigger this error.
fixImplement robust error handling for Dask futures, manage explicit timeouts using `Future.result(timeout=...)` or `distributed.wait(futures, timeout=...)`, and review worker/scheduler logs for underlying causes of unexpected cancellations. Adjust scheduler timeout configurations in cloud environments if 'idle timeouts' are the issue.
TypeError: unhashable type: 'list' (when importing distributed)
This specific TypeError was a known compatibility issue with `distributed` when used with Python versions 3.9.0 and 3.9.1, stemming from internal changes in Python's core.
fixUpgrade your Python installation to version 3.9.2 or newer, or use a Python version older than 3.9.0.
Upgrade
Version history
2026.8.0latest on PyPI · released Aug 24, 2026
Audit
Dependencies
daskrequiredCore dependency for Dask's array, dataframe, etc. objects.
pyarrowrequiredRequired for certain data serialization and I/O operations (>=16 for recent versions).
bokehoptionalRequired to run the Dask diagnostics dashboard.
toolzrequiredUtility library (>=0.12.0 for recent versions).