clearml

library2.1.12pypypi✓ verified 23d ago

ClearML is an open-source MLOps platform that provides auto-magical experiment management, version control for data and models, and MLOps capabilities for AI workflows. It helps track, compare, and reproduce machine learning experiments. The library sees active development with frequent patch releases (multiple per month) and regular minor/major version updates, with the current version being 2.1.5.

ai-ml workflow devops

pip install clearml

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · CLEARML

clearml

ai-mlpythonv2.1.12

Install

7.9s avg

Import

1816ms

Disk

140MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.12 · 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

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 1.862s · 137.2MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 7.9s · import 1.770s · 134MB

140MB installed

● package 140MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Task

✓ from clearml import Task

Dataset

✓ from clearml import Dataset

This quickstart demonstrates how to initialize a ClearML Task to start tracking an experiment. It sets up ClearML credentials via environment variables and then creates a `Task` object. Metrics are logged using the task's logger. It is crucial to call `Task.init()` early in your script to ensure comprehensive tracking. Replace 'YOUR_ACCESS_KEY' and 'YOUR_SECRET_KEY' with your actual ClearML credentials, or run `clearml-init` in your terminal to configure them interactively.

import os from clearml import Task # Set ClearML credentials (replace with your actual keys or configure via `clearml-init` CLI) os.environ['CLEARML_WEB_HOST'] = os.environ.get('CLEARML_WEB_HOST', 'https://app.clear.ml') os.environ['CLEARML_API_HOST'] = os.environ.get('CLEARML_API_HOST', 'https://api.clear.ml') os.environ['CLEARML_FILES_HOST'] = os.environ.get('CLEARML_FILES_HOST', 'https://files.clear.ml') 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') # Initialize a ClearML Task (experiment) task = Task.init(project_name='My Project', task_name='My First ClearML Task') print(f"ClearML Task initialized: {task.name}") # Log a simple metric logger = task.get_logger() for i in range(10): logger.report_scalar(series="loss", value=10 - i, iteration=i) # Simulate some work import time time.sleep(2) # Close the task (optional, often handled automatically on script exit) task.close() print("Task completed and closed.")

clearml --version

Debug

Known issues

breakingClearML v2.1.0 and later removed support for Python versions lower than 3.6. Additionally, work-in-progress to drop Python 2 support was mentioned in v2.1.4, consolidating to Python 3.6+ as the minimum requirement.

fix

Ensure your Python environment is running Python 3.6 or a newer version.

affects: >=2.1.0

breakingFor users self-hosting ClearML Server, upgrading to ClearML Server v2.0.0 or later requires a MongoDB major version upgrade from v5.x to v6.x. If your server is older than v1.17, an intermediate upgrade to v1.17 is necessary before proceeding to v2.0.0. This affects the backend infrastructure rather than the client library directly, but is crucial for compatibility.

fix

Follow the ClearML Server upgrade guide, ensuring MongoDB is upgraded in stages if coming from older server versions. Refer to the ClearML Server documentation for detailed steps.

affects: ClearML Server >=2.0.0

gotchaIt is highly recommended to call `Task.init()` at the very beginning of your script's execution, ideally right after `if __name__ == "__main__:".` Delaying `Task.init()` can lead to missed automatic logging (e.g., from PyTorch, TensorFlow, Matplotlib, Tensorboard), memory leaks, or hanging child processes.

fix

Place `task = Task.init(...)` as early as possible in your main script execution flow.

affects: All

gotchaThe `output_uri` parameter in `Task.init()` defaults to `None` or `False`. If not explicitly set to a storage location (e.g., `'s3://your-bucket/clearml-models'`), models registered by the task will NOT be automatically uploaded to ClearML's backend storage, although their metadata will be logged.

fix

To ensure models are uploaded, set `output_uri='s3://your-bucket/clearml-models'` (or another supported URI) when calling `Task.init()`.

affects: All

gotchaCalling methods like `Task.force_requirements_env_freeze()` or `Task.force_store_standalone_script()` after `Task.init()` can lead to unexpected behavior and might trigger warnings. These methods are intended for pre-initialization configuration.

fix

If these functionalities are needed, ensure they are called *before* `Task.init()` or consider alternative approaches if the goal is to modify an already initialized task.

affects: >=2.0.1

Errors

Common errors & fixes

clearml.backend_api.session.session.LoginError: Failed getting token (error 400 from https://api.clearml.mydomain.com): Bad Request

The ClearML SDK cannot connect to the ClearML server or authenticate due to incorrect server configuration, inaccessible API endpoints, or invalid credentials. This can also manifest as a ConnectTimeoutError.

fix

Ensure `clearml-init` has been run and configured correctly with the right `api.web_server`, `api.api_server`, `api.files_server` addresses, and valid `api.access_key` and `api.secret_key`. Verify network connectivity to the ClearML server components (e.g., API server on port 8008, web on 8080, files on 8081 by default), and confirm the ClearML server is running and accessible.

ModuleNotFoundError: No module named 'clearml'

This error occurs when the Python interpreter cannot find the `clearml` package, often when `clearml-agent` fails to correctly set up the environment or install dependencies within the task's isolated virtual environment, especially if the agent itself is run from a virtual environment without the `--docker` option.

fix

If running `clearml-agent`, install it in your system Python environment (not inside a virtual environment), or ensure the `--docker` option is used to properly isolate task environments. Verify that your task's `requirements.txt` correctly lists `clearml` and its dependencies.

SSL Connection error CERTIFICATE_VERIFY_FAILED

The client machine cannot verify the SSL certificate presented by the ClearML server, which commonly happens with self-signed certificates or misconfigured SSL setups in self-hosted ClearML server instances.

fix

Upgrade the `clearml` Python package to the latest version (`pip install -U clearml`). For development or testing environments where security risks are understood, you can bypass certificate verification by adding `api { verify_certificate = False }` to your `~/clearml.conf` configuration file (or the equivalent path for your OS).

AttributeError: 'Task' object has no attribute 'container'

This `AttributeError` typically indicates an incompatibility between the ClearML SDK version and the server, or attempts to access a `Task` object attribute that has been deprecated, moved, or renamed in newer API versions. This specific error was reported when older `clearml.automation.job.py` tried to access a non-existent `task.data.container` attribute.

fix

Upgrade your `clearml` Python package (`pip install -U clearml`) to the latest version. If the issue persists, consult the ClearML release notes or GitHub issues for specific API changes related to the `Task` object or the `clearml.automation` module.

Upgrade

Version history

2.1.12latest on PyPI · released Aug 19, 2026

Audit

Dependencies

clearml-agentoptionalRequired for remote execution, experiment orchestration, and advanced features like port mapping.

boto3optionalRequired for S3-specific storage configuration.

Agent activity

30 hits · last 30 days

node

OpenAI (training)

Resources

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

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

homepagehttps://clear.ml ↗