{"id":5153,"library":"clearml-agent","title":"ClearML Agent","description":"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.","status":"active","version":"2.0.7","language":"en","source_language":"en","source_url":"https://github.com/clearml/clearml-agent","tags":["MLOps","agent","orchestration","deep learning","machine learning","DevOps","CI/CD","automation"],"install":[{"cmd":"pip install clearml-agent","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Core dependency for interacting with the ClearML server and defining tasks.","package":"clearml","optional":false},{"reason":"Used for system resource monitoring, updated in v2.0.4.","package":"psutil","optional":false},{"reason":"Added for Windows platforms (v1.9.3) for `win32file` functionality.","package":"pywin32","optional":true}],"imports":[],"quickstart":{"code":"# 1. Install ClearML Agent\npip install clearml-agent\n\n# 2. Initialize the agent (interactive setup for server connection and git credentials)\n# You'll be prompted to paste ClearML credentials and optionally configure Git.\n# Ensure CLEARML_API_ACCESS_KEY and CLEARML_API_SECRET_KEY are set as environment variables\n# or paste them when prompted.\n# os.environ['CLEARML_API_ACCESS_KEY'] = os.environ.get('CLEARML_API_ACCESS_KEY', 'YOUR_ACCESS_KEY')\n# os.environ['CLEARML_API_SECRET_KEY'] = os.environ.get('CLEARML_API_SECRET_KEY', 'YOUR_SECRET_KEY')\nclearml-agent init\n\n# 3. Start the ClearML Agent daemon (listening for tasks)\n# For simple virtual environment mode (default):\n# clearml-agent daemon\n\n# For Docker mode (recommended for complex environments):\nclearml-agent daemon --docker","lang":"bash","description":"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`."},"warnings":[{"fix":"Upgrade Python environment to 3.6 or later.","message":"Python 3.5 support was removed in `clearml-agent` v1.9.3. Ensure you are using Python 3.6 or newer.","severity":"breaking","affected_versions":">=1.9.3"},{"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`.","message":"As 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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"Git credentials for cloning repositories can be complex, involving different configuration options and environment variables for various Git providers (GitHub, GitLab, Bitbucket, Azure DevOps).","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}