{
  "schema_version": 2,
  "id": "operate/rs/installing-upgrading/modules/add-module-to-cluster",
  "title": "Install a module on a cluster",
  "url": "https://redis.io/docs/latest/operate/rs/installing-upgrading/modules/add-module-to-cluster/",
  "summary": "",
  "aliases": [
    "/operate/oss_and_stack/stack-with-enterprise/install/add-module-to-cluster/"
  ],
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2026-10-06T08:53:14-07:00",
  "page_type": "content",
  "content_hash": "1a73fdf969f097953eb381abb11793dd75063dc4bd1f50948a94d454efb524b0",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "[Redis Software](https://redis.io/docs/latest/operate/rs) comes packaged with several modules that provide additional Redis capabilities such as [Redis Search](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/search), [JSON](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/json), [time series](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/timeseries), and [probabilistic data structures](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/bloom). As of version 8.0, Redis Software includes multiple feature sets, compatible with different Redis database versions. You can view the installed modules, their versions, and their minimum compatible Redis database versions from **Cluster > Modules** in the Cluster Manager UI.\n\nTo use other modules or upgrade an existing module to a more recent version, you need to install the new module package on your cluster.\n\n> [!WARNING]\n> Some module versions are not supported or recommended for use with Redis Software."
    },
    {
      "id": "module-package-requirements",
      "title": "Module package requirements",
      "role": "content",
      "text": "The module must be packaged as a `.zip` file containing:\n\n- **module.json**: A metadata file with module information including:\n  - `module_name`: The actual module name\n  - `version`: Numeric version\n  - `semantic_version`: Semantic version string (for example, \"1.0.0\")\n  - `min_redis_version`: Minimum compatible Redis version\n  - `commands`: List of commands the module provides\n  - `capabilities`: List of module capabilities\n\n- **Module binary**: The compiled `.so` file for the target platform"
    },
    {
      "id": "get-packaged-modules",
      "title": "Get packaged modules",
      "role": "content",
      "text": "To install or upgrade a module on a [Redis Software](https://redis.io/docs/latest/operate/rs) cluster, you need a module package.\n\n- For versions of official Redis modules that are not available from the [Redis download center](https://redis.io/downloads/), [contact support](https://redis.io/support/).\n\n- For custom-packaged modules, download a [custom-packaged module](https://redislabs.com/community/redis-modules-hub/) from the developer.\n\n- User-defined modules are downloaded automatically if you [add them during bootstrapping](#bootstrap-user-defined-module)."
    },
    {
      "id": "bootstrap-user-defined-module",
      "title": "Add user-defined modules during bootstrapping (Redis Software v8.0.6 and later)",
      "role": "content",
      "text": "As of Redis Software version 8.0.6, you can include `user_defined_modules` in REST API requests to [initiate boostrap operations](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/bootstrap#post-bootstrap) such as `create_cluster`, `join_cluster`, or `recover_cluster`. Each node in the cluster independently downloads and installs the specified modules during its bootstrap process.\n\n`user_defined_modules` has the following JSON schema:\n\n[code example]"
    },
    {
      "id": "best-practices",
      "title": "Best practices",
      "role": "content",
      "text": "- Use `https` instead of `http` for secure module downloads.\n\n- Include version numbers in module URLs.\n\n- Use the same `user_defined_modules` configuration for all nodes in a cluster.\n\n- If using authenticated downloads, ensure credentials are properly secured.\n\n- Ensure modules are compatible with the Redis database version running on your cluster.\n\n- Verify modules work correctly before deploying to production environments."
    },
    {
      "id": "example-requests",
      "title": "Example requests",
      "role": "example",
      "text": "**Create cluster:**\n\nThe following example creates a cluster with multiple modules:\n\n\n[code example]\n\n**Join cluster:**\n\nThe following example joins a node to a cluster with multiple modules:\n\n[code example]\n\n**Recover cluster:**\n\nThe following example recovers a cluster with multiple modules:\n\n[code example]"
    },
    {
      "id": "troubleshooting",
      "title": "Troubleshooting",
      "role": "errors",
      "text": "#### Error handling\n\nDownload failures do not fail the bootstrap process. If a module fails to download or install, a warning is logged and the bootstrap process continues with the remaining modules.\n\nWarnings are recorded in the bootstrap status with:\n- `warning_type`: `\"module_download_failed\"`\n- `message`: Error description\n- `details`: `{\"module_name\": \"<name>\"}`\n\n#### Module download failed\n\nCheck the bootstrap logs for detailed error messages:\n\n[code example]\n\nCommon causes:\n- Invalid URL\n- Network connectivity issues\n- Authentication failures\n- Module package format issues\n\n#### Module compatibility errors\n\nAfter processing user-defined modules, the system validates that all custom modules are compatible with existing databases in the cluster. This validation:\n\n1. Checks which custom modules are used by existing databases.\n\n1. Verifies that compatible module versions are available on the node.\n\n1. Fails the bootstrap process if incompatible modules are detected.\n\nIf the bootstrap process fails with an `incompatible_modules` error:\n\n1. Verify the module version is compatible with existing databases.\n\n1. Ensure the module binary exists and is accessible.\n\n#### Missing module.json\n\nIf you see `\"module.json missing\"` errors:\n\n1. Verify the zip file contains a valid `module.json` at the root level.\n\n1. Verify the JSON is properly formatted."
    },
    {
      "id": "add-user-defined-module-to-cluster",
      "title": "Add a user-defined module to a cluster (Redis Software v8.0.x and later)",
      "role": "content",
      "text": "To add a custom module to a cluster running Redis Software version 8.0.x or later, use the following REST API requests:\n\n1. [Upload the custom module configuration](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/modules/user-defined#post-user-defined-module). Replace the values in the following example with your own.\n\n    [code example]\n\n1. For each node in the cluster, [upload the custom module artifact](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/modules/user-defined#post-local-user-defined-artifacts):\n\n    [code example]\n\n    The *module* parameter specifies the full path of the module artifact and must be submitted as form-data. In addition, the module artifact must be available and accessible to the server processing the request."
    },
    {
      "id": "add-a-module-to-a-cluster",
      "title": "Add a module to a cluster (Redis Software v7.22.x and earlier)",
      "role": "content",
      "text": "Use one of the following methods to add a module to a cluster running Redis Software version 7.22.x or earlier:\n\n**Cluster Manager UI:**\n\nTo add a module to the cluster using the Cluster Manager UI:\n\n1. Go to **Cluster > Modules**.\n\n1. Select **Upload module**.\n\n1. Use the file browser to add the packaged module.\n\n**REST API:**\n\nTo add a module to the cluster using the REST API:\n\n1. Copy the module package to a node in the cluster.\n\n1. Add the module to the cluster with a [`POST` request to the `/v2/modules`](https://redis.io/docs/latest/operate/rs/references/rest-api/requests/modules#post-module-v2) endpoint:\n\n    [code example]\n\n    Here, the *module* parameter specifies the full path of the module package and must be submitted as form-data. In addition, the package must be available and accessible to the server processing the request.\n\n1. If the module installation succeeds, the `POST` request returns a [JSON object](https://redis.io/docs/latest/operate/rs/references/rest-api/objects/module) that represents the new module. If it fails, it may return a JSON object with an `error_code` and `description` with more details.\n\n\n\nFor RedisGears, follow these [installation instructions](https://redis.io/docs/latest/operate/oss_and_stack/stack-with-enterprise/deprecated-features/gears-v1/installing-redisgears) instead.\n\n> [!WARNING]\n> We recommend consulting [Redis support](https://redis.io/support/) before you upgrade a module on the cluster, especially if the cluster is used in production."
    },
    {
      "id": "next-steps",
      "title": "Next steps",
      "role": "content",
      "text": "- Create a database and [enable the new module](https://redis.io/docs/latest/operate/rs/installing-upgrading/modules/add-module-to-database).\n- [Upgrade a module](https://redis.io/docs/latest/operate/rs/installing-upgrading/modules/upgrade-module) to the new version."
    }
  ],
  "examples": [
    {
      "id": "bootstrap-user-defined-module-ex0",
      "language": "json",
      "code": "{\n  \"user_defined_modules\": [\n    {\n      \"name\": \"string (required)\",\n      \"location\": {\n        \"location_type\": \"http | https (required)\",\n        \"url\": \"string (required)\",\n        \"credentials\": {\n          \"username\": \"string (optional)\",\n          \"password\": \"string (optional)\"\n        }\n      }\n    }\n  ]\n}",
      "section_id": "bootstrap-user-defined-module"
    },
    {
      "id": "example-requests-ex0",
      "language": "sh",
      "code": "POST /v1/bootstrap/create_cluster\n{\n  \"action\": \"create_cluster\",\n  \"credentials\": {\n    \"username\": \"admin@example.com\",\n    \"password\": \"your-secure-password\"\n  },\n  \"cluster\": {\n    \"name\": \"my-cluster.example.com\"\n  },\n  \"user_defined_modules\": [\n    {\n      \"name\": \"ModuleA\",\n      \"location\": {\n        \"location_type\": \"https\",\n        \"url\": \"https://private-repo.example.com/enterprise-module-2.0.0.zip\",\n        \"credentials\": {\n          \"username\": \"download-user\",\n          \"password\": \"download-password\"\n        }\n      }\n    },\n    {\n      \"name\": \"ModuleB\",\n      \"location\": {\n        \"location_type\": \"https\",\n        \"url\": \"https://modules.example.com/module-b-2.5.0.zip\"\n      }\n    },\n    {\n      \"name\": \"ModuleC\",\n      \"location\": {\n        \"location_type\": \"http\",\n        \"url\": \"http://internal-server.local/module-c-1.2.0.zip\"\n      }\n    }\n  ]\n}",
      "section_id": "example-requests"
    },
    {
      "id": "example-requests-ex1",
      "language": "sh",
      "code": "POST /v1/bootstrap/join_cluster\n{\n  \"action\": \"join_cluster\",\n  \"credentials\": {\n    \"username\": \"admin@example.com\",\n    \"password\": \"your-secure-password\"\n  },\n  \"cluster\": {\n    \"name\": \"my-cluster.example.com\",\n    \"nodes\": [\"192.168.1.10\", \"192.168.1.11\"]\n  },\n  \"user_defined_modules\": [\n    {\n      \"name\": \"ModuleA\",\n      \"location\": {\n        \"location_type\": \"https\",\n        \"url\": \"https://private-repo.example.com/enterprise-module-2.0.0.zip\",\n        \"credentials\": {\n          \"username\": \"download-user\",\n          \"password\": \"download-password\"\n        }\n      }\n    },\n    {\n      \"name\": \"ModuleB\",\n      \"location\": {\n        \"location_type\": \"https\",\n        \"url\": \"https://modules.example.com/module-b-2.5.0.zip\"\n      }\n    },\n    {\n      \"name\": \"ModuleC\",\n      \"location\": {\n        \"location_type\": \"http\",\n        \"url\": \"http://internal-server.local/module-c-1.2.0.zip\"\n      }\n    }\n  ]\n}",
      "section_id": "example-requests"
    },
    {
      "id": "example-requests-ex2",
      "language": "sh",
      "code": "POST /v1/bootstrap/recover_cluster\n{\n  \"action\": \"recover_cluster\",\n  \"recovery_filename\": \"/path/to/backup.rdb\",\n  \"credentials\": {\n    \"username\": \"admin@example.com\",\n    \"password\": \"your-secure-password\"\n  },\n  \"user_defined_modules\": [\n    {\n      \"name\": \"ModuleA\",\n      \"location\": {\n        \"location_type\": \"https\",\n        \"url\": \"https://private-repo.example.com/enterprise-module-2.0.0.zip\",\n        \"credentials\": {\n          \"username\": \"download-user\",\n          \"password\": \"download-password\"\n        }\n      }\n    },\n    {\n      \"name\": \"ModuleB\",\n      \"location\": {\n        \"location_type\": \"https\",\n        \"url\": \"https://modules.example.com/module-b-2.5.0.zip\"\n      }\n    },\n    {\n      \"name\": \"ModuleC\",\n      \"location\": {\n        \"location_type\": \"http\",\n        \"url\": \"http://internal-server.local/module-c-1.2.0.zip\"\n      }\n    }\n  ]\n}",
      "section_id": "example-requests"
    },
    {
      "id": "troubleshooting-ex0",
      "language": "plaintext",
      "code": "Failed to download and install custom module '<name>': <error details>",
      "section_id": "troubleshooting"
    },
    {
      "id": "add-user-defined-module-to-cluster-ex0",
      "language": "sh",
      "code": "POST https://<host>:<port>/v2/modules/user-defined\n    {\n      \"module_name\": \"TestModule\",\n      \"version\": 1,\n      \"semantic_version\": \"0.0.1\",\n      \"display_name\": \"test module\",\n      \"commands\": [\n        {\n          \"command_arity\": -1,\n          \"command_name\": \"module.command\",\n          \"first_key\": 1,\n          \"flags\": [\"write\"],\n          \"last_key\": 1,\n          \"step\": 1\n        }\n      ],\n      \"command_line_args\": \"\",\n      \"capabilities\": [\"list\", \"of\", \"capabilities\"],\n      \"min_redis_version\": \"2.1\"\n    }",
      "section_id": "add-user-defined-module-to-cluster"
    },
    {
      "id": "add-user-defined-module-to-cluster-ex1",
      "language": "sh",
      "code": "POST https://<host>:<port>/v2/local/modules/user-defined/artifacts\n    \"module=@/tmp/custom-module.zip\"",
      "section_id": "add-user-defined-module-to-cluster"
    },
    {
      "id": "add-a-module-to-a-cluster-ex0",
      "language": "sh",
      "code": "POST https://<host>:<port>/v2/modules\n    \"module=@/tmp/redisearch.Linux-ubuntu16.04-x86_64.2.2.6.zip\"",
      "section_id": "add-a-module-to-a-cluster"
    }
  ]
}