Using DDEV Add-ons

November 28, 2025 ยท View on GitHub

DDEV add-ons are pre-packaged extensions that add functionality to your development environment with a single command. They handle installation, configuration, and integration automatically.

Add-ons vs. Custom Docker Compose Services

Use add-ons when:

  • A standard, tested service is available as an add-on (Redis, Elasticsearch, Solr)
  • You want automatic configuration and setup

Use custom Docker Compose services when:

  • You need a custom or highly specialized service
  • You require deep customization of the service configuration
  • You're prototyping or experimenting with service configurations

See Defining Additional Services with Docker Compose for custom Docker Compose service setup.

Discovering Add-ons

Web-based Add-on Registry

Use DDEV Add-on Registry to discover, explore, and leave comments on available add-ons.

Command Line Discovery

List all available add-ons:

ddev add-on list

Search for specific add-ons by name or description:

# Search for Redis-related add-ons
ddev add-on search redis

# Search with multiple terms (all must be present)
ddev add-on search redis web

# Search with multiple terms using quotes (currently same behavior)
ddev add-on search "redis insight"

Installing Add-ons

Public Add-ons

Install any public add-on using the repository format:

ddev add-on get <owner>/<repo>

Examples:

# Download the official Redis add-on
ddev add-on get ddev/ddev-redis

# Get debug info about `ddev add-on get` failure
ddev add-on get ddev/ddev-redis --verbose

# Download the official Redis add-on, version v1.0.4
ddev add-on get ddev/ddev-redis --version v1.0.4

# Download the Drupal Solr add-on from its v1.2.3 release tarball
ddev add-on get https://github.com/ddev/ddev-drupal-solr/archive/refs/tags/v1.2.3.tar.gz

# Download the Drupal Contrib add-on from its main branch tarball
ddev add-on get https://github.com/ddev/ddev-drupal-contrib/tarball/main

# Download the OpenSearch add-on from a pull request #15 tarball
ddev add-on get https://github.com/ddev/ddev-opensearch/tarball/refs/pull/15/head

# Copy an add-on available in another directory
ddev add-on get /path/to/package

# Copy an add-on from a tarball in another directory
ddev add-on get /path/to/tarball.tar.gz

# Download the official Redis add-on and install it into a project named "my-project"
ddev add-on get ddev/ddev-redis --project my-project

Add-ons are installed into your project's .ddev directory and automatically integrated with your project configuration.

Private Add-ons

Add-ons from private GitHub repositories are supported, but you have to provide a GitHub token with the correct privileges to allow access to them:

!!!tip "Can I reuse my token from a different environment variable?" Yes, supported environment variables include:

- `DDEV_GITHUB_TOKEN` (highest priority)
- `GH_TOKEN` (lower priority than `DDEV_GITHUB_TOKEN`)
- `GITHUB_TOKEN` (lowest priority)

export DDEV_GITHUB_TOKEN=<your-github-token>

# Get the private add-on from the latest stable release
ddev add-on get <owner>/<repo>

# Or get a tarball for a specific branch, tag, or commit SHA
ddev add-on get https://api.github.com/repos/<owner>/<repo>/tarball/<ref>

# Note: the format below may not work with fine-grained tokens
ddev add-on get https://github.com/<owner>/<repo>/tarball/<ref>

Private repositories on other platforms:

git clone <private-repo-url> /tmp/private-addon
ddev add-on get /tmp/private-addon

Managing Add-ons

View Installed Add-ons

ddev add-on list --installed

Update an Add-on

ddev add-on get <owner>/<repo>

This updates to the latest version while preserving your customizations.

Remove an Add-on

ddev add-on remove <addon-name>

This cleanly removes all add-on files and configurations.

Customizing Add-on Configuration

Sometimes you need to customize an add-on's default configuration.

Many add-ons support customization through environment variables. For example, to change the Redis version in ddev-redis:

ddev dotenv set .ddev/.env.redis --redis-tag 7-bookworm
ddev restart

This sets REDIS_TAG="7-bookworm" which the add-on uses during service startup.

You can also edit the .ddev/.env.redis file directly:

REDIS_TAG="7-bookworm"
REDIS_FOO="bar"

!!!tip "Check add-on documentation" Each add-on documents its available environment variables. Check the add-on's GitHub repository for configuration options.

Method 2: Docker Compose Override

For more complex customizations, create an override file. For example, .ddev/docker-compose.redis_extra.yaml:

services:
  redis:
    image: redis:7-bookworm
    command: ["redis-server", "--maxmemory", "256mb"]

This approach:

  • Maintains your customizations when updating the add-on
  • Allows complex service modifications
  • Doesn't require modifying the original add-on files

!!!note Remove the #ddev-generated line from any add-on file you customize directly, but using override files is preferred.

Official Add-ons

Database and Caching

Search and Analytics

Development Tools

Platform and Cloud Integration

Specialized Services

Development Environment

Troubleshooting Add-ons

Check Add-on Status

ddev describe

ddev logs -s <service>

This shows logs from an add-on's service.

Explore Add-on Files

ls -la .ddev/

Look for files created by the add-on, typically:

  • docker-compose.<addon-name>.yaml
  • Configuration files in .ddev/<addon-name>/
  • Custom commands in .ddev/commands/

Restart Services

ddev restart

This restarts all services and applies any configuration changes.

Review Add-on Configuration

ddev utility compose-config

This shows the final Docker Compose configuration including add-on services.

Common Issues

Service not starting: Check ddev logs -s <service> for error messages from the add-on service.

Configuration not applied: Ensure you've run ddev restart after making configuration changes.

Getting Help

  • Add-on documentation: Check the add-on's GitHub repository readme
  • DDEV Discord: Join the DDEV Discord for community support
  • GitHub Issues: Report add-on-specific issues to the add-on's repository

Next Steps