API Reference

Python API Reference

coiled.Cluster([name, n_workers, ...])

Create a Dask cluster with Coiled

coiled.cluster_cost_estimate([n_workers, ...])

Estimate the cluster hourly cost

coiled.cluster_logs(name[, account])

Retrieve logs from a Coiled cluster.

coiled.create_cluster_configuration(name, ...)

Create a cluster configuration

coiled.create_job_configuration(name, ...[, ...])

Create a job configuration

coiled.create_notebook(name, *[, account, ...])

Create a notebook

coiled.create_software_environment([name, ...])

Create a software environment

coiled.delete_cluster(name[, account])

Delete a cluster

coiled.delete_cluster_configuration(name)

Delete a cluster configuration

coiled.delete_job_configuration(name)

Delete a job configuration

coiled.delete_software_environment(name)

Delete a software environment

coiled.diagnostics([account])

Run a diagnose check aimed to help support with any issues.

coiled.get_notifications([json, account, ...])

Get a list of all recent notifications.

coiled.get_software_info(name[, account])

Retrieve solved spec for a Coiled software environment

coiled.install(name)

Create a Coiled software environment locally

coiled.job_logs(name[, account])

Retrieve logs from a Coiled job.

coiled.list_cluster_configurations([account])

List cluster configurations

coiled.list_clusters([account])

List clusters

coiled.list_core_usage([json, account])

Get a list of used cores.

coiled.list_job_configurations([account])

List job configurations

coiled.list_jobs([account])

List jobs

coiled.list_local_versions([json])

Get information about local versions.

coiled.list_performance_reports([account])

List performance reports stored on Coiled Cloud

coiled.list_software_environments([account])

List software environments

coiled.list_user_information()

List information about your user.

coiled.performance_report([filename, ...])

Generates a static performance report and saves it to Coiled Cloud

coiled.set_backend_options([...])

Configure account level settings for cloud provider and container registry.

coiled.start_job(configuration[, account, ...])

Start a job

coiled.stop_job(name)

Stop a running job

Software Environments

coiled.create_software_environment(name=None, *, account=None, conda=None, pip=None, container=None, log_output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, post_build=None, conda_env_name=None, backend_options=None, private=False, force_rebuild=False, environ=None)[source]

Create a software environment

Parameters
  • name (Optional[str]) – Name of software environment. Name can’t contain uppercase letters.

  • account (Optional[str]) – The account in which to create the software environment, if not given in the name.

  • conda (Union[list, dict, str, None]) – Specification for packages to install into the software environment using conda. Can be a list of packages, a dictionary, or a path to a conda environment YAML file.

  • pip (Union[list, str, None]) – Packages to install into the software environment using pip. Can be a list of packages or a path to a pip requirements file.

  • container (Optional[str]) – Docker image to use for the software environment. Must be the name of a docker image on Docker hub. Defaults to coiled/default.

  • post_build (Union[list, str, None]) – List of commands or path to a local executable script to run after pip and conda packages have been installed.

  • log_output – Stream to output logs to. Defaults to sys.stdout.

  • conda_env_name (Optional[str]) – Name of conda environment to install packages into. Note that this should only be used when specifying a non-default value for container and when the non-default Docker image used expects commands to run in a conda environment not named “coiled”. Defaults to “coiled”.

  • backend_options (Optional[Dict]) – Dictionary of backend specific options (e.g. {'region': 'us-east-2'}). Any options specified with this keyword argument will take precedence over those stored in the coiled.backend-options configuration value.

  • private (bool) – Whether this software environment is private or public. Defaults to False

  • force_rebuild (bool) – By default, if an existing software environment with the same name and dependencies already exists, a rebuild is aborted. If this is set to True, those checks are skipped and the environment will be rebuilt. Defaults to False

  • environ (Optional[Dict]) – Dictionary of environment variables.

Return type

None

coiled.delete_software_environment(name)[source]

Delete a software environment

Parameters

name – Name of software environment to delete.

coiled.get_software_info(name, account=None)[source]

Retrieve solved spec for a Coiled software environment

Parameters

name (str) – Software environment name

Returns

Coiled software environment information

Return type

results

coiled.inspect(name)[source]

View the details of a Coiled software environment

Parameters

name (str) –

Identifier of the software environment to use, in the format (<account>/)<name>. If the software environment is owned by the same account as that passed into “account”, the (<account>/) prefix is optional.

For example, suppose your account is “wondercorp”, but your friends at “friendlycorp” have an environment named “xgboost” that you want to use; you can specify this with “friendlycorp/xgboost”. If you simply entered “xgboost”, this is shorthand for “wondercorp/xgboost”.

The “name” portion of (<account>/)<name> can only contain ASCII letters, hyphens and underscores.

Examples

>>> import coiled
>>> coiled.inspect("coiled/default")
coiled.install(name)[source]

Create a Coiled software environment locally

Parameters

name

Identifier of the software environment to use, in the format (<account>/)<name>. If the software environment is owned by the same account as that passed into “account”, the (<account>/) prefix is optional.

For example, suppose your account is “wondercorp”, but your friends at “friendlycorp” have an environment named “xgboost” that you want to use; you can specify this with “friendlycorp/xgboost”. If you simply entered “xgboost”, this is shorthand for “wondercorp/xgboost”.

The “name” portion of (<account>/)<name> can only contain ASCII letters, hyphens and underscores.

Examples

>>> import coiled
>>> coiled.install("coiled/default")
coiled.list_software_environments(account=None)[source]

List software environments

Parameters

account – Name of the Coiled account to list software environments. If not provided, will use the coiled.account configuration value.

Returns

Dictionary with information about each software environment in the specified account. Keys in the dictionary are names of software environments, while the values contain information about the corresponding software environment.

Cluster Configurations

coiled.create_cluster_configuration(name, software, *, account=None, worker_cpu=1, worker_gpu=0, worker_memory='4 GiB', worker_class='dask.distributed.Nanny', worker_options=None, scheduler_cpu=1, scheduler_memory='4 GiB', scheduler_class='dask.distributed.Scheduler', scheduler_options=None, private=False)[source]

Create a cluster configuration

Parameters
  • name (str) – Name of cluster configuration. Optionally prefixed with an account name like “myaccount/myname”

  • software (str) –

    Identifier of the software environment to use, in the format (<account>/)<name>. If the software environment is owned by the same account as that passed into “account”, the (<account>/) prefix is optional.

    For example, suppose your account is “wondercorp”, but your friends at “friendlycorp” have an environment named “xgboost” that you want to use; you can specify this with “friendlycorp/xgboost”. If you simply entered “xgboost”, this is shorthand for “wondercorp/xgboost”.

    The “name” portion of (<account>/)<name> can only contain ASCII letters, hyphens and underscores.

  • account (Optional[str]) – The account in which to create the cluster configuration, if not given in the name.

  • worker_cpu (int) – Number of CPUs allocated for each worker. Defaults to 1.

  • worker_gpu (int) – Number of GPUs allocated for each worker. Defaults to 0 (no GPU support). Note that this will _always_ allocate GPU-enabled workers, so is expensive.

  • worker_memory (str) – Amount of memory to allocate for each worker. Defaults to 4 GiB.

  • worker_class (str) – Worker class to use. Defaults to “dask.distributed.Nanny”.

  • worker_options (Optional[dict]) – Mapping with keyword arguments to pass to worker_class. Defaults to {}.

  • scheduler_cpu (int) – Number of CPUs allocated for the scheduler. Defaults to 1.

  • scheduler_memory (str) – Amount of memory to allocate for the scheduler. Defaults to 4 GiB.

  • scheduler_class (str) – Scheduler class to use. Defaults to “dask.distributed.Scheduler”.

  • scheduler_options (Optional[dict]) – Mapping with keyword arguments to pass to scheduler_class. Defaults to {}.

  • private (bool) – Whether this cluster configuration is private or public. Defaults to False

See also

dask.utils.parse_bytes

Return type

None

coiled.delete_cluster_configuration(name)[source]

Delete a cluster configuration

Parameters

name – Name of cluster configuration to delete.

coiled.list_cluster_configurations(account=None)[source]

List cluster configurations

Parameters

account – Name of the Coiled account to list cluster configurations. If not provided, will use the coiled.account configuration value.

Returns

Dictionary with information about each cluster configuration in the specified account. Keys in the dictionary are names of cluster configurations, while the values contain information about the corresponding cluster configuration.

Clusters

class coiled.Cluster(name=None, *, n_workers=4, configuration=None, software=None, worker_cpu=None, worker_gpu=None, worker_gpu_type=None, worker_memory=None, worker_class=None, worker_options=None, worker_vm_types=None, scheduler_cpu=None, scheduler_memory=None, scheduler_class=None, scheduler_options=None, scheduler_vm_types=None, asynchronous=False, cloud=None, account=None, shutdown_on_close=None, backend_options=None, credentials='account', timeout=None, environ=None, protocol=None)[source]

Create a Dask cluster with Coiled

Parameters
  • n_workers (int) – Number of workers in this cluster. Defaults to 4.

  • configuration (Optional[str]) – Name of cluster configuration to create cluster from. If not specified, defaults to coiled/default for the current Python version.

  • name (Optional[str]) – Name to use for identifying this cluster. Defaults to None.

  • software (Optional[str]) –

    Identifier of the software environment to use, in the format (<account>/)<name>. If the software environment is owned by the same account as that passed into “account”, the (<account>/) prefix is optional.

    For example, suppose your account is “wondercorp”, but your friends at “friendlycorp” have an environment named “xgboost” that you want to use; you can specify this with “friendlycorp/xgboost”. If you simply entered “xgboost”, this is shorthand for “wondercorp/xgboost”.

    The “name” portion of (<account>/)<name> can only contain ASCII letters, hyphens and underscores.

  • worker_cpu (Optional[int]) – Number of CPUs allocated for each worker. Defaults to 2.

  • worker_gpu (Optional[int]) – Number of GPUs allocated for each worker. Defaults to 0 (no GPU support). Note that this will _always_ allocate GPU-enabled workers, so is expensive. This option will always allocate on demand instances, you can change this behaviour by using "spot": False on the backend_options parameter.

  • worker_gpu_type (Optional[str]) – Type of GPU to use for this cluster. You can only select GPU type if you are using GCP as your backend. You can run the command coiled.list_gpu_types() to see a list of allowed GPUs.

  • worker_memory (Optional[str]) – Amount of memory to allocate for each worker. Defaults to 8 GiB.

  • worker_class (Optional[str]) – Worker class to use. Defaults to “dask.distributed.Nanny”.

  • worker_options (Optional[dict]) – Mapping with keyword arguments to pass to worker_class. Defaults to {}.

  • worker_vm_types (Optional[list]) – List of instance types that you would like workers to use, this list can have up to five items. You can use the command coiled.list_instance_types() to se a list of allowed types.

  • scheduler_cpu (Optional[int]) – Number of CPUs allocated for the scheduler. Defaults to 1.

  • scheduler_memory (Optional[str]) – Amount of memory to allocate for the scheduler. Defaults to 4 GiB.

  • scheduler_class (Optional[str]) – Scheduler class to use. Defaults to “dask.distributed.Scheduler”.

  • scheduler_options (Optional[dict]) – Mapping with keyword arguments to pass to scheduler_class. Defaults to {}.

  • scheduler_vm_types (Optional[list]) – List of instance types that you would like the scheduler to use, this list can have up to five items. You can use the command coiled.list_instance_types() to se a list of allowed types.

  • asynchronous (bool) – Set to True if using this Cloud within async/await functions or within Tornado gen.coroutines. Otherwise this should remain False for normal use. Default is False.

  • cloud (Optional[Cloud]) – Cloud object to use for interacting with Coiled.

  • account (Optional[str]) – Name of Coiled account to use. If not provided, will default to the user account for the cloud object being used.

  • shutdown_on_close – Whether or not to shut down the cluster when it finishes. Defaults to True, unless name points to an existing cluster.

  • backend_options (Optional[Dict]) – Dictionary of backend specific options (e.g. {'region': 'us-east-2'}). Any options specified with this keyword argument will take precedence over those stored in the coiled.backend-options cofiguration value.

  • credentials (Optional[str]) – Which credentials to use for Dask operations and forward to Dask clusters – options are “account”, “local”, or “none”. The default behavior is to prefer credentials associated with the Coiled Account, if available, then try to use local credentials, if available. NOTE: credential handling currently only works with AWS credentials.

  • timeout (Optional[int]) – Timeout in seconds to wait for a cluster to start, will use default_cluster_timeout set on parent Cloud by default.

  • environ (Optional[Dict[str, str]]) – Dictionary of environment variables.

  • protocol (Optional[str]) – Communication protocol for the cluster. Default is tls.

adapt(Adaptive=<class 'coiled.cluster.CoiledAdaptive'>, **kwargs)[source]

Dynamically scale the number of workers in the cluster based on scaling heuristics.

Parameters
  • minimum (int) – Minimum number of workers that the cluster should have while on low load, defaults to 1.

  • maximum (int) – Maximum numbers of workers that the cluster should have while on high load. If maximum is not set, this value will be based on your core count limit. This value is also capped by your core count limit.

  • wait_count (int) – Number of consecutive times that a worker should be suggested for removal before the cluster removes it, defaults to 60.

  • interval (timedelta or str) – Milliseconds between checks, default sto 5000 ms.

  • target_duration (timedelta or str) – Amount of time we want a computation to take. This affects how aggressively the cluster scales up, defaults to 5s.

Return type

Adaptive

close()[source]

Close the cluster.

Return type

Optional[Awaitable[None]]

get_logs(scheduler=True, workers=True)[source]

Return logs for the scheduler and workers :type scheduler: bool :param scheduler: Whether or not to collect logs for the scheduler :type scheduler: boolean :type workers: bool :param workers: Whether or not to collect logs for the workers :type workers: boolean

Returns

logs – A dictionary of logs, with one item for the scheduler and one for the workers

Return type

Dict[str]

property loop
property plan
async recommendations(target)[source]

Make scale up/down recommendations based on current state and target

Return type

dict

property requested
scale(n)[source]

Scale cluster to n workers

Parameters

n (int) – Number of workers to scale cluster size to.

Return type

Optional[Awaitable[None]]

async scale_down(workers)[source]
Return type

None

async scale_up(n)[source]
Return type

None

sync(func, *args, asynchronous=None, callback_timeout=None, **kwargs)[source]
Return type

Union[~_T, Awaitable[~_T]]

async workers_to_close(target)[source]

Determine which, if any, workers should potentially be removed from the cluster.

Notes

Cluster.workers_to_close dispatches to Scheduler.workers_to_close(), but may be overridden in subclasses.

Returns

Return type

List of worker addresses to close, if any

See also

Scheduler.workers_to_close

coiled.cluster_cost_estimate(n_workers=4, configuration=None, worker_cpu=None, worker_gpu=None, worker_memory=None, scheduler_cpu=None, scheduler_memory=None, backend_options=None)[source]

Estimate the cluster hourly cost

Parameters
  • n_workers (int) – Number of workers in this cluster. Defaults to 4.

  • configuration (Optional[str]) – Name of cluster configuration to create cluster from. If not specified, defaults to coiled/default for the current Python version.

  • worker_cpu (Optional[int]) – Number of CPUs allocated for each worker. Defaults to 1.

  • worker_gpu (Optional[int]) – Number of GPUs allocated for each worker. Defaults to 0 (no GPU support). Note that this will _always_ allocate GPU-enabled workers, so is expensive.

  • worker_memory (Union[str, int, None]) – Amount of memory to allocate for each worker. Defaults to 4 GiB.

  • scheduler_cpu (Optional[int]) – Number of CPUs allocated for the scheduler. Defaults to 1.

  • scheduler_memory (Union[str, int, None]) – Amount of memory to allocate for the scheduler. Defaults to 4 GiB.

  • backend_options (Optional[Dict]) – Dictionary of backend specific options (e.g. {'region': 'us-east-2'}). Any options specified with this keyword argument will take precedence over those stored in the coiled.backend-options cofiguration value.

See also

dask.utils.parse_bytes

Return type

str

coiled.cluster_logs(name, account=None)[source]

Retrieve logs from a Coiled cluster.

Parameters
  • name (str) – Cluster name

  • account (Optional[str]) – The account in which the cluster is running

Returns

The logs from the cluster.

Return type

logs

coiled.delete_cluster(name, account=None)[source]

Delete a cluster

Parameters

name (str) – Name of cluster to delete.

coiled.list_clusters(account=None)[source]

List clusters

Parameters

account – Name of the Coiled account to list clusters. If not provided, will use the coiled.account configuration value.

Returns

Dictionary with information about each cluster in the specified account. Keys in the dictionary are names of clusters, while the values contain information about the corresponding cluster.

coiled.list_core_usage(json=False, account=None)[source]

Get a list of used cores.

Returns a table that shows the limit of cores that the user can use and a breakdown of the core usage split up between account, user, clusters and jobs.

Parameters
  • account (Optional[str]) – Name of the Coiled account to list core usage. If not provided, will use the coiled.account configuration value.

  • json (bool) – If set to True, it will return this list in json format instead of a table.

Return type

Optional[dict]

Performance Reports

coiled.list_performance_reports(account=None)[source]

List performance reports stored on Coiled Cloud

Returns a list of dicts that contain information about Coiled Cloud hosted performance reports

Parameters

account – Associated account for which the user wishes to get reports from. If not specified, current / default account will be utilized.

Return type

List[Dict]

coiled.performance_report(filename='dask-report.html', private=False, account=None)[source]

Generates a static performance report and saves it to Coiled Cloud

This context manager lightly wraps Dask’s performance_report. It generates a static performance report and uploads it to Coiled Cloud. After uploading, it prints out the url where the report is hosted. For a list of hosted performance reports, utilize coiled.list_performance_reports(). Note each user is limited to 5 hosted reports with each a maximum file size of 10mb.

Parameters
  • filename – The file name of the performance report file.

  • private – If set to True, the uploaded performance report is only accessible to logged in Coiled users who are members of the current / default or specified account.

  • account – Associated the account which user wishes to upload to. If not specified, current / default account will be utilized.

Return type

Generator[None, None, None]

Notebooks

coiled.create_notebook(name, *, account=None, container='coiled/notebook:latest', conda=None, pip=None, post_build=None, cpu=1, gpu=0, memory='4 GiB', files=None, command=('/bin/bash', 'start.sh', 'jupyter', 'lab'), ports=(8888,), description=None, environ=None)[source]

Create a notebook

This allows you to create a hosted notebook which is runnable on https://cloud.coiled.io.

Parameters
  • name – Name of the notebook.

  • account (Optional[str]) – The account to save the notebook in. Note that if “account” is provided and “name” uses the format “<account>/name”, an error will be thrown if the two accounts differ.

  • container – Docker image to use for the notebook’s software environment. Defaults to coiled/notebook:latest. Note that when using a non-default container, you should check whether the default command is compatible with the container being used and, if not, update the command such that it launches a Jupyter session within the container.

  • conda – Specification for packages to install into the notebook’s software environment using conda. Can be a list of packages, a dictionary, or a path to a conda environment YAML file.

  • pip – Packages to install into the notebook’s software environment using pip. Can be a list of packages or a path to a pip requirements file.

  • post_build – List of commands or path to a local executable script to run after pip and conda packages have been installed.

  • cpu (int) – Number of CPUs allocated for the notebook session. Defaults to 1.

  • gpu (int) – Number of GPUs allocated for the notebook session. Defaults to 0 (no GPU support).

  • memory (str) – Amount of memory to allocated for the notebook session. Defaults to 4 GiB.

  • files – List of local files to upload.

  • command – Command to run. If not specified, defaults to running JupyterLab.

  • ports – List of ports to expose. If not specified, defaults to (8888,)

  • description – Description for notebook.

  • environ (Optional[Dict]) – Dictionary of environment variables.

Jobs

coiled.create_job_configuration(name, command, software, *, account=None, cpu=1, gpu=0, memory='4 GiB', ports=None, files=None, description=None)[source]

Create a job configuration

Parameters
  • name (str) – Name of the job configuration Optionally prefixed with an account name like “myaccount/myname”

  • command (List[str]) – Command to run this job. Defaults to None.

  • software (str) –

    Identifier of the software environment to use, in the format (<account>/)<name>. If the software environment is owned by the same account as that passed into “account”, the (<account>/) prefix is optional.

    For example, suppose your account is “wondercorp”, but your friends at “friendlycorp” have an environment named “xgboost” that you want to use; you can specify this with “friendlycorp/xgboost”. If you simply entered “xgboost”, this is shorthand for “wondercorp/xgboost”.

  • account (Optional[str]) – The coiled account in which to create the configuration.

  • cpu (int) – Number of CPUs allocated for this job. Defaults to 1.

  • gpu (int) – Number of GPUs allocated for this job. Defaults to 0.

  • memory (str) – Ammount of memory allocated for this job. Defaults to 4 GiB.

  • ports (Optional[List]) – List of ports to expose. Defaults to None.

  • files (Union[str, List[str], None]) – List of local files to upload.

  • description (Optional[str]) – Description for the job.

Return type

None

coiled.delete_job_configuration(name)[source]

Delete a job configuration

Parameters

name – Name of job configuration to delete.

coiled.job_logs(name, account=None)[source]

Retrieve logs from a Coiled job.

Parameters
  • name (str) – Job name

  • account (Optional[str]) – The account in which the job is run

Returns

Coiled job logs

Return type

logs

coiled.list_job_configurations(account=None)[source]

List job configurations

Parameters

account – Name of the Coiled account to list job configurations. If not provided, will use the coiled.account configuration value.

Returns

Dictionary with information about each job configuration in the specified account. Keys in the dictionary are names of job configurations, while the values contain information about the corresponding job configuration.

coiled.list_jobs(account=None)[source]

List jobs

Parameters

account – Name of the Coiled account to list jobs. If not provided, will use the coiled.account configuration value.

Returns

Dictionary with information about each job in the specified account. Keys in the dictionary are names of jobs, while the values contain information about the corresponding job.

coiled.start_job(configuration, account=None, backend_options=None, environ=None, log_output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>)[source]

Start a job

Parameters
  • configuration (str) – Name of the job configuration to create the job from.

  • account (Optional[str]) – Name of Coiled account to use. If not provided, will default to the user account for the cloud object being used.

  • backend_options (Optional[Dict]) – Dictionary of backend specific options (e.g. {'region': 'us-east-2'}). Any options specified with this keyword argument will take precedence over those stored in the coiled.backend-options cofiguration value

  • environ (Optional[Dict]) – Dictionary of environment variables.

  • log_output – Stream to output logs to. Defaults to sys.stdout.

coiled.stop_job(name)[source]

Stop a running job

Parameters

name (str) –

Name of job to stop.

You can get a list of running jobs and their names by using the command coiled.list_jobs()

Backend

coiled.set_backend_options(use_coiled_defaults=False, account=None, backend='aws', create_vpc=False, aws_region='us-east-1', aws_access_key_id=None, aws_secret_access_key=None, gcp_service_creds_file=None, gcp_service_creds_dict=None, gcp_project_id=None, gcp_region=None, gcp_zone=None, azure_resource_group=None, azure_client_id=None, azure_secret=None, azure_subscription_id=None, azure_tenant=None, azure_region='eastus', registry_type='ecr', registry_namespace=None, registry_access_token=None, registry_uri='docker.io', registry_username=None, log_output=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, **kwargs)[source]

Configure account level settings for cloud provider and container registry.

This method configures account level backend settings for cloud providers, container registries, and setting up an account-level VPC for running clusters and other Coiled managed resources.

Parameters
  • use_coiled_default – Boolean to reset backend options to Coiled default settings which are for the AWS VM backend with default region of us-east-1.

  • account (Optional[str]) – Coiled account to configure if user has access. If not specified, current / default account will be utilized.

  • backend_type – Supported backends such as AWS VM (vm_aws), GCP VM (vm_gcp) and Azure VM (vm_azure).

  • create_vpc (bool) – For supported backends, when create_vpc=True options will create a VPC (or reuse an existing one) inside of the user account of the specified region for the cloud provider credentials supplied. Note that supplying valid credentials for cloud provider is required for Coiled to manage the setup, configure and access policies for users of this account.

  • aws_region (str) – The region which Coiled cloud resources will be deployed to and where other resources such as the docker registry are located or where a specified VPC will be created.

  • aws_access_key_id (Optional[str]) – For AWS support backend, this argument is required to create or use an existing Coiled managed VPC.

  • aws_secret_access_key (Optional[str]) – For AWS support backend, this argument is required to create or use an existing Coiled managed VPC.

  • gcp_service_creds_file (Optional[str]) – A string filepath to a Google Cloud Compute service account json credentials file used for creating and managing a Coiled VPC.

  • gcp_service_creds_dict (Optional[dict]) – A dictionary of the contents of a Google Cloud Compute service account json credentials file used for creating a VPC to host Coiled Cloud related assets.

  • gcp_project_id (Optional[str]) – The Google Cloud Compute project id in which a VPC will be created to host Coiled Cloud related assets.

  • gcp_region (Optional[str]) – The Google Cloud Compute region name in which a VPC will be created.

  • gcp_zone (Optional[str]) – The Google Cloud Compute zone name in which a subnet will be create (Zone should be <region>-<zone letter>) for example zone C for us-east1 should be specified as us-east1-c.

  • azure_resource_group (Optional[str]) – The Azure resource name where the cluster will be created.

  • azure_client_id (Optional[str]) – The Azure clientId credential

  • azure_secret (Optional[str]) – The Azure clientSecret credential

  • azure_subscription_id (Optional[str]) – The Azure subscriptionId

  • azure_tenant (Optional[str]) – The Azure tenantId

  • azure_region (str) – An Azure region.

  • registry_type (Literal[‘ecr’, ‘docker_hub’, ‘gar’, ‘acr’]) – Custom software environments are stored in a docker container registry. By default, container images will be stored in AWS ECR. Users are able to store contains on a private registry by providing additional configuration registry_* arguments and specifying registry_type=’docker_hub’. To use Google Artifact Registry, pass registry_type=’gar’, gcp_project_name, gcp_region_name, and one of gcp_service_creds_dict or gcp_service_creds_file. To use Azure Container Registry, pass registry_type=’acr’, azure_resource_group, azure_client_id, azure_secret, azure_subscription_id, azure_tenant, and azure_region.

  • registry_uri (str) – The container registry URI. Defaults to docker.io. Only required if registry_type=’docker_hub’.

  • registry_username (Optional[str]) – A registry username (should be lowercased). Only required if registry_type=’docker_hub’.

  • registry_namespace (Optional[str]) – A namespace for storing the container images. Defaults to username if not specified. More information about docker namespaces can be found here: https://docs.docker.com/docker-hub/repos/#creating-repositories. Only required if registry_type=’docker_hub’.

  • registry_access_token (Optional[str]) – A token to access registry images. More information about access tokens ca be found here: https://docs.docker.com/docker-hub/access-tokens/. Only required if registry_type=’docker_hub’.

Information

coiled.diagnostics(account=None)[source]

Run a diagnose check aimed to help support with any issues.

This command will call others to dump information that could help in troubleshooting issues. This command will return a json that will make it easier for you to share with the Coiled support team if needed.

Parameters

account (Optional[str]) – Name of the Coiled account to list core usage. If not provided, will use the coiled.account configuration value.

Return type

dict

coiled.get_notifications(json=False, account=None, limit=100, level=0)[source]

Get a list of all recent notifications.

Parameters
  • account (Optional[str]) – Name of the Coiled account to list notifications. If not provided, will use the coiled.account configuration value.

  • json (bool) – If set to True, it will return this list in json format instead of a table.

  • limit (int) – The max number of notifications to return.

  • level (Union[int, str]) – A constant from the standard python logging library (e.g., logging.INFO), or a string of one of the following: debug, info, warning, error, or critical. This will be used to filter the returned notifications.

Return type

Optional[List[dict]]

coiled.list_local_versions(json=False)[source]

Get information about local versions.

Returns the versions of Python, Coiled, Dask and Distributed that are installed locally. This information could be useful when troubleshooting issues.

Parameters

json (bool) – If set to True, it will return this list in json format instead of a table.

Return type

Optional[dict]

coiled.list_user_information()[source]

List information about your user.

This command will give you more information about your account, which teams you are part of and any limits that your account might have.

Return type

dict

Command Line API Reference

coiled login

Configure your Coiled account credentials

coiled login [OPTIONS]

Options

-s, --server <server>

Coiled server to use

-t, --token <token>

Coiled user token

-a, --account <account>

Coiled account

--retry, --no-retry

Whether or not to automatically ask for a new token if an invalid token is entered

coiled install

Create Coiled conda software environment locally

coiled install [OPTIONS] NAME

Arguments

NAME

Required argument

coiled env create

Create a Coiled software environment

coiled env create [OPTIONS]

Options

-n, --name <name>

Name of software environment, it must be lowercase.

--container <container>

Base docker image to use.

--conda <conda>

Conda environment file.

--pip <pip>

Pip requirements file.

--post-build <post_build>

Post-build script.

--conda-env-name <conda_env_name>

Name of conda environment to install packages into. Only use when using –container, and the image expects commands to run in a conda environment not named “coiled”

--private

Flag to set software environment private.

--force-rebuild

Skip checks for an existing software environment build.

-e, --environ <environ>

Custom environment variable(s).

coiled env delete

Delete a Coiled software environment

coiled env delete [OPTIONS] NAME

Arguments

NAME

Required argument

coiled env list

List the Coiled software environments in an account

coiled env list [OPTIONS] [ACCOUNT]

Arguments

ACCOUNT

Optional argument

coiled env inspect

View the details of a Coiled software environment

coiled env inspect [OPTIONS] NAME

Arguments

NAME

Required argument