{"id":7203,"library":"elasticsearch-curator","title":"Elasticsearch Curator","description":"Elasticsearch Curator is a tool designed to manage Elasticsearch indices and snapshots programmatically via YAML configuration files. It simplifies tasks like deleting old indices, optimizing shards, or closing/opening indices. Currently at version 9.0.0, it follows an active release cadence, with major releases aligning with Elasticsearch versions and frequent patch releases for bug fixes and minor features.","status":"active","version":"9.0.0","language":"en","source_language":"en","source_url":"https://github.com/elastic/curator","tags":["elasticsearch","index management","data lifecycle","automation","cli"],"install":[{"cmd":"pip install elasticsearch-curator","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Official Elasticsearch Python client wrapper, used internally for all API interactions.","package":"es_client"},{"reason":"Used for parsing and processing the YAML configuration and action files.","package":"PyYAML"},{"reason":"Used for building the command-line interface.","package":"Click"}],"imports":[{"note":"While `curator` can be imported, it's primarily designed as a command-line tool. Direct programmatic use is possible via `curator.api` but less common for full lifecycle management.","symbol":"curator","correct":"import curator"},{"note":"Allows advanced users to programmatically invoke Curator's CLI functions, though `subprocess` is typically preferred for invoking the `curator` command.","symbol":"cli","correct":"from curator import cli"}],"quickstart":{"code":"import subprocess\nimport os\n\n# Most common usage is via CLI with configuration files.\n# Example: Create a dummy action file and run curator in dry-run.\n\n# Create a dummy action configuration file\naction_config_content = \"\"\"\nactions:\n  1:\n    action: delete_indices\n    description: \"Delete indices older than 30 days matching 'logstash-'\"\n    options:\n      ignore_empty_list: True\n      timeout_override:\n      continue_if_exception: False\n      disable_action: False\n      dry_run: True # Always set dry_run in example code for safety\n    filters:\n      - filtertype: pattern\n        kind: prefix\n        value: logstash-\n      - filtertype: age\n        source: name\n        direction: older\n        unit: days\n        unit_count: 30\n\"\"\"\naction_file_path = \"curator_action.yml\"\nwith open(action_file_path, \"w\") as f:\n    f.write(action_config_content)\n\ntry:\n    # Get Curator version to check installation\n    print(\"Checking Curator version:\")\n    version_result = subprocess.run(\n        [\"curator\", \"--version\"], capture_output=True, text=True, check=True\n    )\n    print(version_result.stdout.strip())\n\n    # Simulate running an action in dry-run mode\n    print(\"\\nSimulating an index deletion action (dry-run):\")\n    # Note: A client configuration is typically also needed in a separate file,\n    # or specified via CLI arguments like --host, --port etc.\n    # For simplicity, this example assumes default client config or\n    # that ES is running on localhost:9200 and no auth is needed.\n    # For a real run, create a 'curator.yml' client config file or pass\n    # client options directly.\n    dry_run_result = subprocess.run(\n        [\"curator\", \"--host\", \"localhost\", \"--port\", \"9200\", action_file_path, \"--dry-run\"],\n        capture_output=True,\n        text=True,\n        check=True\n    )\n    print(dry_run_result.stdout)\n    if dry_run_result.stderr:\n        print(\"STDERR:\", dry_run_result.stderr)\n\nexcept FileNotFoundError:\n    print(\"Error: 'curator' command not found. Is elasticsearch-curator installed?\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Curator command failed with exit code {e.returncode}\")\n    print(f\"STDOUT: {e.stdout}\")\n    print(f\"STDERR: {e.stderr}\")\nfinally:\n    if os.path.exists(action_file_path):\n        os.remove(action_file_path)\n\nprint(\"\\nThis demonstrates how to run a Curator action in dry-run mode.\")\nprint(\"For actual index management, remove '--dry-run' and ensure Elasticsearch is running.\")\nprint(\"Refer to official documentation for full client and action configuration.\")\n","lang":"python","description":"The primary way to use Elasticsearch Curator is via its command-line interface with YAML configuration files for client settings and actions. This quickstart demonstrates how to check the installed version and simulate an action in dry-run mode using Python's `subprocess` module, which is common for interacting with CLI tools."},"warnings":[{"fix":"Upgrade your Python environment to 3.10, 3.11, 3.12, or 3.13 before installing Curator 9.x.","message":"Curator 9.x requires Python 3.10 or later. Python 3.8 and 3.9 are no longer supported.","severity":"breaking","affected_versions":"9.0.0 and later"},{"fix":"If you need to manage Elasticsearch 8.x clusters, use Curator 8.0.21 or an earlier 8.x release. Do not upgrade to Curator 9.x for ES 8.x clusters.","message":"Curator 9.x exclusively supports Elasticsearch 9.x. It is not compatible with Elasticsearch 8.x or older versions.","severity":"breaking","affected_versions":"9.0.0 and later"},{"fix":"Upgrade to Curator 8.0.18 or later. Always use `--dry-run` to review planned actions before executing them on live clusters.","message":"A critical bug in Curator 8.0.17 (and earlier 8.x versions) with the `age` filter could erroneously delete indices that did not match the `timestring` pattern, leading to unintended data loss.","severity":"gotcha","affected_versions":"8.0.0 - 8.0.17"},{"fix":"Upgrade to Curator 8.0.21 or later to ensure `--ignore_empty_list` is correctly honored in all singletons.","message":"The `--ignore_empty_list` option was not respected in Curator 8.0.20 and earlier, potentially causing actions to fail if no indices matched the filters.","severity":"gotcha","affected_versions":"8.0.0 - 8.0.20"},{"fix":"Upgrade to Curator 8.0.14 or later, which includes `es_client==8.12.9` correcting this behavior. Always verify your configuration with `--dry-run`.","message":"In Curator 8.0.13, default values from command-line options could incorrectly override settings defined in configuration files due to an `es_client` bug.","severity":"gotcha","affected_versions":"8.0.13"},{"fix":"For most use cases, generate YAML configuration files and invoke `curator` via `subprocess` from your Python application. Refer to the official documentation for CLI usage.","message":"Curator is primarily a command-line interface (CLI) application. While a Python API exists, programmatic use as a library is not its main design goal and might require more complex setup than intended.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade your Python environment to 3.10, 3.11, 3.12, or 3.13. Alternatively, install Curator 8.x (`pip install 'elasticsearch-curator<9'`) if you must use an older Python.","cause":"Attempting to run Curator 9.x on an unsupported Python version.","error":"RuntimeError: Python 3.8 and 3.9 are no longer supported. Please upgrade to Python 3.10 or later."},{"fix":"If managing Elasticsearch 9.x, ensure your `client` configuration points to an ES 9.x cluster. If managing ES 8.x, downgrade Curator to 8.0.21 or an earlier 8.x version using `pip install 'elasticsearch-curator<9'`.","cause":"Curator 9.x is attempting to connect to an Elasticsearch 8.x cluster, which is incompatible.","error":"elasticsearch.exceptions.UnsupportedProductError: The client noticed that the server is not Elasticsearch and is not supported by this client version."},{"fix":"Review your `curator.yml` (client config) and action YAML files against the official Curator documentation. Ensure proper YAML syntax and that all mandatory fields are present and correctly formatted.","cause":"Your YAML configuration file for Curator (client or action) is malformed, missing required keys, or contains invalid values.","error":"curator.exceptions.ConfigurationError: Missing a required setting. Check your configuration file."},{"fix":"Ensure `pip install elasticsearch-curator` completed successfully. If installed in a virtual environment, activate it. If using `pipx`, ensure `curator` is added to your path. You might also need to ensure your `~/.local/bin` is in your PATH.","cause":"The `curator` executable is not in your system's PATH, or `elasticsearch-curator` was not installed correctly.","error":"bash: curator: command not found"}]}