Command Line Interface

Dask provides a dask executable for a command line interface. Dask’s CLI is designed to be extensible allowing other projects in the Dask ecosystem (such as distributed) to add subcommands.

Built-in commands

dask comes with the following commands.

dask info

Information about your dask installation.

dask info [OPTIONS] COMMAND [ARGS]...

versions

Print versions of Dask related projects.

dask info versions [OPTIONS]

dask docs

Open Dask documentation (https://docs.dask.org/) in a web browser.

dask docs [OPTIONS]

Extending the Dask CLI

Note

This section is intended for library authors who want to integrate their library with the dask CLI.

Third party packages can extend the dask command line tool via entry points and Click. Dask will discover click.Command and click.Group objects registered as entry points under the dask_cli namespace. Below you’ll find two examples which augment the dask CLI by adding a dask_cli entry point to a project.

Click provides great documentation for writing commands; more documentation on entry points can be found at:

Example: PEP-621

Since PEP-621, if starting a new project, the canonical way to add an entry point to your Python project is to use the [project.entry-points] table in the pyproject.toml file. This method should be picked up by any Python build system that is compatible with PEP-621’s project configuration. Hatch, Flit, and setuptools (version 61.0.0 or later) are three example build systems which are PEP-621 compatible and use [project.entry-points].

For example, if your project is called mypackage, and it contains a cli.py module under the mypackage namespace with the following contents:

# in the file mypackage/cli.py
import click

@click.command(name="mycommand")
@click.argument("name", type=str)
@click.option("-c", "--count", default=1)
def main(name, count):
    for _ in range(count):
        click.echo(f"hello {name} from mycommand!")

You can create an entry point that will be discovered by Dask by adding to pyproject.toml:

[project.entry-points."dask_cli"]
mycommand = "mypackage.cli:main"

After installing mypackage, the mycommand subcommand should be available to the dask CLI:

$ dask mycommand world
hello world from mycommand!

$ dask mycommand user -c 3
hello user from mycommand!
hello user from mycommand!
hello user from mycommand!

Example: setup.cfg and setup.py

Note

If you are starting a new project the recommendation from the Python Packaging Authority (PyPA) is to use PEP-621, these setuptools instructions are provided for existing projects.

If your project already uses setuptools with a setup.cfg file and/or a setup.py file, we can create an entry point for the same mycommand.cli:main function introduced in the previous section. If using setup.cfg, the entry point can be registered by adding the following block to the file:

[options.entry_points]
dask_cli =
    mycommand = mypackage.cli:main

Or the entry point can be registered directly in setup.py with:

from setuptools import setup

setup(
    ...
    entry_points="""
        [dask_cli]
        mycommand=mypackage.cli:main
    """,
)