Registry / aws / clearml-agent

clearml-agent

library2.0.7pypypiunverified

ClearML Agent is a Python library that provides auto-magical DevOps capabilities for Deep Learning. It serves as a worker to execute machine learning tasks remotely, integrating with the ClearML Python package and ClearML Server. The library maintains an active release cadence with frequent updates.

aws ai-ml devops

pip install clearml-agent

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLEARML-AGENT

clearml-agent

awspythonv2.0.7

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

The ClearML Agent is primarily a CLI tool. This quickstart guides through installation, interactive initialization to connect to a ClearML server and configure Git, and finally starting the agent daemon to listen for and execute tasks. For a full non-interactive setup, consider setting environment variables for credentials and pre-configuring `clearml.conf`.

# 1. Install ClearML Agent pip install clearml-agent # 2. Initialize the agent (interactive setup for server connection and git credentials) # You'll be prompted to paste ClearML credentials and optionally configure Git. # Ensure CLEARML_API_ACCESS_KEY and CLEARML_API_SECRET_KEY are set as environment variables # or paste them when prompted. # os.environ['CLEARML_API_ACCESS_KEY'] = os.environ.get('CLEARML_API_ACCESS_KEY', 'YOUR_ACCESS_KEY') # os.environ['CLEARML_API_SECRET_KEY'] = os.environ.get('CLEARML_API_SECRET_KEY', 'YOUR_SECRET_KEY') clearml-agent init # 3. Start the ClearML Agent daemon (listening for tasks) # For simple virtual environment mode (default): # clearml-agent daemon # For Docker mode (recommended for complex environments): clearml-agent daemon --docker

clearml-agent --version

Debug

Known issues

breakingPython 3.5 support was removed in `clearml-agent` v1.9.3. Ensure you are using Python 3.6 or newer.

fix

Upgrade Python environment to 3.6 or later.

affects: >=1.9.3

breakingAs of `clearml-agent` v1.1.0, the agent no longer tries to use the demo server by default. Attempting to run without explicit server configuration will fail.

fix

Run `clearml-agent init` to configure server credentials or set `CLEARML_NO_DEFAULT_SERVER=0` environment variable for backward compatibility with older demo server behavior, or define `api_server`, `web_server`, `files_server` in `clearml.conf`.

affects: >=1.1.0

gotchaWhen running tasks in Docker mode, the agent by default installs all required Python packages. To use a pre-built Docker image without additional installations, you must explicitly disable this behavior.

fix

Set environment variables `CLEARML_AGENT_SKIP_PIP_VENV_INSTALL=1` or `CLEARML_AGENT_SKIP_PYTHON_ENV_INSTALL=1` for the agent's environment, or clear the 'Python Packages' section of the task in the ClearML UI before enqueuing.

affects: All versions

gotchaGit credentials for cloning repositories can be complex, involving different configuration options and environment variables for various Git providers (GitHub, GitLab, Bitbucket, Azure DevOps).

fix

Configure Git credentials during `clearml-agent init`, or use `agent.git.extra_credentials`, `agent.git_host_match_prefix`, `agent.git_use_azure_pat`, `agent.git_use_ms_entra_token` in `clearml.conf`. Environment variables like `CLEARML_AGENT_GIT_USER` and `CLEARML_AGENT_GIT_PASS` can also be used.

affects: All versions

gotchaIf running the agent in virtual environment mode (pip, conda, poetry), the agent itself cannot be launched from an *already activated* virtual environment. It needs to create its own isolated environments.

fix

Run `clearml-agent daemon` from the system Python environment, not within an activated virtual environment. The agent will then create and manage virtual environments for each task it executes.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'clearml'

The `clearml` Python package is not installed in the environment where the task is being executed, or there is an issue with the Python environment used by `clearml-agent`.

fix

Ensure the `clearml` package is installed in the appropriate environment (e.g., the virtual environment or Docker image used by the agent) using `pip install clearml`.

AttributeError: type object 'Callable' has no attribute '_abc_registry'

This error typically arises from compatibility issues or an outdated `typing` package, especially in Conda environments, where `typing` is part of the standard library but might be installed as a separate, conflicting package.

fix

Uninstall the separately installed `typing` package using `pip uninstall typing`, as Python 3.5+ includes `typing` in its standard library.

clearml_agent: ERROR: Connection Error: it seems *api_server* is misconfigured. Is this the ClearML API server http://HOST_IP:8082 ?

The `clearml-agent` cannot establish a connection to the ClearML server, often due to an incorrect `api_server` URL, invalid API credentials, or network connectivity issues configured in `clearml.conf` or via environment variables.

fix

Verify the `api_server` URL, `access_key`, and `secret_key` in your `~/clearml.conf` file (or corresponding environment variables like `CLEARML_API_SERVER`, `CLEARML_API_ACCESS_KEY`, `CLEARML_API_SECRET_KEY`) and ensure the ClearML server is accessible from the agent's machine.

clearml_agent: ERROR: expected SCALAR, SEQUENCE-START, MAPPING-START, or ALIAS

This indicates a syntax error within the `clearml.conf` configuration file, commonly caused by incorrect YAML formatting such as improper indentation, unquoted strings, or malformed data structures.

fix

Review the `~/clearml.conf` file for any YAML syntax errors, paying close attention to indentation, ensure strings are properly quoted, and validate the structure against a correct ClearML configuration example.

Upgrade

Version history

2.0.7latest on PyPI · released Feb 9, 2026

Audit

Dependencies

clearmlrequiredCore dependency for interacting with the ClearML server and defining tasks.

psutilrequiredUsed for system resource monitoring, updated in v2.0.4.

pywin32optionalAdded for Windows platforms (v1.9.3) for `win32file` functionality.

Agent activity

18 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/clearml/clearml-agent ↗

packagehttps://pypi.org/project/clearml-agent/ ↗

homepagehttps://clear.ml ↗