{"id":5154,"library":"clearml","title":"ClearML","description":"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.","status":"active","version":"2.1.5","language":"en","source_language":"en","source_url":"https://github.com/clearml/clearml","tags":["MLOps","experiment tracking","version control","ML","orchestration","datasets"],"install":[{"cmd":"pip install clearml","lang":"bash","label":"Install core library"}],"dependencies":[{"reason":"Required for remote execution, experiment orchestration, and advanced features like port mapping.","package":"clearml-agent","optional":true},{"reason":"Required for S3-specific storage configuration.","package":"boto3","optional":true}],"imports":[{"symbol":"Task","correct":"from clearml import Task"},{"symbol":"Dataset","correct":"from clearml import Dataset"}],"quickstart":{"code":"import os\nfrom clearml import Task\n\n# Set ClearML credentials (replace with your actual keys or configure via `clearml-init` CLI)\nos.environ['CLEARML_WEB_HOST'] = os.environ.get('CLEARML_WEB_HOST', 'https://app.clear.ml')\nos.environ['CLEARML_API_HOST'] = os.environ.get('CLEARML_API_HOST', 'https://api.clear.ml')\nos.environ['CLEARML_FILES_HOST'] = os.environ.get('CLEARML_FILES_HOST', 'https://files.clear.ml')\nos.environ['CLEARML_API_ACCESS_KEY'] = os.environ.get('CLEARML_API_ACCESS_KEY', 'YOUR_ACCESS_KEY')\nos.environ['CLEARML_API_SECRET_KEY'] = os.environ.get('CLEARML_API_SECRET_KEY', 'YOUR_SECRET_KEY')\n\n# Initialize a ClearML Task (experiment)\ntask = Task.init(project_name='My Project', task_name='My First ClearML Task')\n\nprint(f\"ClearML Task initialized: {task.name}\")\n\n# Log a simple metric\nlogger = task.get_logger()\nfor i in range(10):\n    logger.report_scalar(series=\"loss\", value=10 - i, iteration=i)\n\n# Simulate some work\nimport time\ntime.sleep(2)\n\n# Close the task (optional, often handled automatically on script exit)\ntask.close()\nprint(\"Task completed and closed.\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure your Python environment is running Python 3.6 or a newer version.","message":"ClearML 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.","severity":"breaking","affected_versions":">=2.1.0"},{"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.","message":"For 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.","severity":"breaking","affected_versions":"ClearML Server >=2.0.0"},{"fix":"Place `task = Task.init(...)` as early as possible in your main script execution flow.","message":"It 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.","severity":"gotcha","affected_versions":"All"},{"fix":"To ensure models are uploaded, set `output_uri='s3://your-bucket/clearml-models'` (or another supported URI) when calling `Task.init()`.","message":"The `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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"Calling 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.","severity":"gotcha","affected_versions":">=2.0.1"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}