# Installing and Updating an Extension

KeyDB supports Redis-compatible modules to extend core database functionality with custom data types, specialized algorithms, and advanced operations. These modules are compiled as shared object (<span class="s3">.so</span>) files and must be loaded at server startup. Examples include RedisBloom, RedisJSON, and RedisTimeSeries all of which are supported in KeyDB just as in Redis.

In Elestio-hosted KeyDB instances or any Docker Compose–based setup, modules can be mounted and loaded via configuration in <span class="s3">docker-compose.yml</span>. This guide outlines how to install, load, and manage KeyDB modules using Docker Compose, including verification steps, update methods, and best practices.

## **Installing and Enabling KeyDB Modules**

Modules in KeyDB must be loaded at server startup using the <span class="s3">--loadmodule</span> directive. These are <span class="s3">.so</span> binaries that are typically mounted into the container from the host file system. The process is nearly identical to Redis module integration.

#### **Update docker-compose.yml**

To use a module such as RedisBloom in a KeyDB Docker setup, mount the module file and add the <span class="s3">--loadmodule</span> directive to the container command.

```yaml
services:
  keydb:
    image: eqalpha/keydb:latest
    volumes:
      - ./modules/redisbloom.so:/data/redisbloom.so
    command: ["keydb-server", "--loadmodule", "/data/redisbloom.so"]
    ports:
      - "6379:6379"
```

Here:

- <span class="s1">./modules/redisbloom.so</span> is the local path on your host machine.
- <span class="s1">/data/redisbloom.so</span> is the path where the module will be accessible inside the container.

Ensure that the <span class="s2">.so</span> file exists locally before running the container.

#### **Restart the KeyDB Service**

After updating the Docker Compose configuration, apply changes by restarting the container:

```
docker-compose down
docker-compose up -d
```

This reloads KeyDB and ensures the module is initialized during startup.

#### **Verify the Module is Loaded**

Once KeyDB is running, connect to the containerized service:

```bash
docker-compose exec keydb keydb-cli -a <yourPassword>
```

Run the following command to check for loaded modules:

```bash
MODULE LIST
```

Expected output (for RedisBloom):

```bash
1) 1) "name"
   2) "bf"
   3) "ver"
   4) (integer) 20207
```

This confirms that the module (in this case, <span class="s1">bf</span> for Bloom filters) has been loaded successfully.

## **Checking Module Availability &amp; Compatibility**

KeyDB modules must match the container’s runtime architecture and the KeyDB version. Many Redis modules work out-of-the-box with KeyDB, but always check the official documentation or test in a controlled environment first.

To inspect module metadata and compatibility:

```
INFO MODULES
```

To confirm the current KeyDB version and platform:

```
docker-compose exec keydb keydb-server --version
```

If a module fails to load, check container logs for detailed error output:

```
docker-compose logs keydb
```

Most load failures are caused by missing binaries, unsupported formats, or incorrect file paths.

## **Updating or Unloading Modules**

KeyDB does not support dynamic unloading of modules while the server is running. To update or remove a module, the server must be stopped and restarted with the revised configuration.

Stop the container:

```
docker-compose down
```

<span class="s1">Edit </span>docker-compose.yml<span class="s1"> as needed:</span>

- Update the <span class="s1">.so</span> path to reference the new module version.
- Remove the <span class="s1">--loadmodule</span> line to disable the module entirely.

Start the container again:

```
docker-compose up -d
```

Always test updated modules in staging before deploying to production environments.

## **Troubleshooting Common Module Issues**

<table border="1" id="bkmrk-issue-cause-resoluti" style="border-collapse: collapse; border-color: rgb(0, 0, 0);"><thead><tr><th style="border-color: rgb(0, 0, 0);">**Issue**

</th><th style="border-color: rgb(0, 0, 0);">**Cause**

</th><th style="border-color: rgb(0, 0, 0);">**Resolution**

</th></tr></thead><tbody><tr><td style="border-color: rgb(0, 0, 0);">KeyDB fails to start

</td><td style="border-color: rgb(0, 0, 0);">Invalid module path or incompatible binary

</td><td style="border-color: rgb(0, 0, 0);">Check <span class="s1">docker-compose logs keydb</span> and verify path and architecture

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">MODULE command not recognized

</td><td style="border-color: rgb(0, 0, 0);">Image does not include module support

</td><td style="border-color: rgb(0, 0, 0);"><span class="s1">Use an image like </span>eqalpha/keydb<span class="s1"> or </span>eqalpha/keydb:alpine

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">“Can’t open .so file” error

</td><td style="border-color: rgb(0, 0, 0);">Volume not mounted or file permission denied

</td><td style="border-color: rgb(0, 0, 0);">Confirm that the <span class="s1">.so</span> file exists and has readable permissions

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Module not listed in MODULE LIST

</td><td style="border-color: rgb(0, 0, 0);">Silent module load failure

</td><td style="border-color: rgb(0, 0, 0);">Review container logs and validate command syntax

</td></tr><tr><td style="border-color: rgb(0, 0, 0);">Module commands not recognized

</td><td style="border-color: rgb(0, 0, 0);">Module did not load correctly

</td><td style="border-color: rgb(0, 0, 0);">Ensure Redis version and module binary compatibility

</td></tr></tbody></table>

## **Security Considerations**

Modules execute native code within the KeyDB process and inherit its permissions. As such, only load trusted <span class="s1">.so</span> files compiled from official or reviewed source code. Avoid uploading or using third-party binaries without auditing. In Elestio-managed or containerized environments, use Docker’s file and user isolation to reduce risk:

- Set read-only permissions on mounted <span class="s1">.so</span> files.
- Use non-root users inside containers when possible.
- Monitor module behavior with SLOWLOG, INFO, and command auditing.

Improperly configured or malicious modules can cause crashes, memory leaks, or worse. Treat modules as privileged extensions and keep them versioned and tested across environments.