Install Only the Plugins You Need on a Slim Kestra Image

Table of Contents

For the complete documentation index, see llms.txt. For a full content snapshot, see llms-full.txt. Append .md to any kestra.io/docs/* URL for plain Markdown.

Install only the plugins your flows use on top of the slim Kestra image.

Kestra ships two flavors of its Docker image:

The default image (kestra/kestra for OSS, kestra-ee for Enterprise), which bundles all plugins.
The slim image (with the -slim suffix, formerly -no-plugins), which ships without plugins for a smaller footprint and faster startup.

Plugins are JAR files that Kestra loads from /app/plugins at startup. To add a selected set to the slim image, use kestractl, the recommended tool for downloading plugins:

Download the plugins you need into a local plugins/ directory with kestractl.
Copy that directory into a custom image, or mount it into the container with Docker Compose.
Verify the plugins are present.

The same kestractl commands prepare plugins for a standalone server or a remote worker without Docker.

For local development in open source Kestra, plugin auto-install may be enough: Kestra fetches a missing plugin from Maven Central when you save a flow that uses it. Auto-install is on by default with local storage (for example, server local), and KESTRA_PLUGINS_AUTO_INSTALL_ENABLED=true turns it on elsewhere. Enterprise uses Versioned Plugins instead.

Prerequisites

Docker installed and authenticated to your registry.

For the Enterprise base image, log in to the Kestra registry with your license credentials:

docker login registry.kestra.io \
  --username "$KESTRA_LICENSE_ID" \
  --password "$KESTRA_LICENSE_FINGERPRINT"

kestractl installed. See kestractl installation, or run:

curl -fsSL https://raw.githubusercontent.com/kestra-io/kestractl/main/install-scripts/install.sh | bash

Download the plugins

By default, kestractl writes plugins to a local ./plugins directory. The --compatible-for flag resolves the plugin version that matches your Kestra release, so you don’t need to look up version numbers. In the commands on this page, replace <version> with your Kestra version (for example, 2.0.2).

Open source plugins

Open source plugins are published to Maven Central, so you don’t need to authenticate. To download one plugin:

kestractl plugins get io.kestra.plugin:plugin-dbt --compatible-for <version>

To download several plugins in one command, repeat --plugins:

kestractl plugins download --compatible-for <version> \
  --plugins io.kestra.plugin:plugin-dbt \
  --plugins io.kestra.plugin:plugin-script-python \
  --plugins io.kestra.storage:storage-s3 \
  --plugins-dir ./plugins

To find plugin coordinates, run kestractl plugins list <version>, which prints every plugin compatible with that Kestra version.

Enterprise plugins

Enterprise plugins and external backends, such as secret managers, are served from the Kestra plugin registry. Pass your license credentials to download them:

kestractl plugins download --compatible-for <version> \
  --plugins io.kestra.plugin.ee:plugin-ee-salesforce \
  --plugins-dir ./plugins \
  --maven-repository https://registry.kestra.io/maven \
  --maven-username "$KESTRA_LICENSE_ID" \
  --maven-password "$KESTRA_LICENSE_FINGERPRINT"

Add the plugins to Kestra

Choose one approach. A custom image is the better fit for production and distributed deployments because every component runs the same artifact. Mounting a directory is quicker for a single Docker Compose host.

Option 1: Build a custom image

Create a Dockerfile next to your plugins/ directory. Use the base image for your edition:

# Enterprise Edition
FROM registry.kestra.io/docker/kestra-ee:v<version>-slim

# Open Source
# FROM kestra/kestra:v<version>-slim

COPY --chown=kestra:kestra plugins/ /app/plugins/

Build the image locally:

docker build -t kestra:custom-<version> .

The version in the base image tag and the version you pass to --compatible-for must match. Mismatched versions cause plugin loading failures at runtime.

In a distributed deployment, every Kestra component (Executor, Webserver, and Workers) must run the exact same Docker image. Build one custom image and use it across all components.

Option 2: Mount the plugins with Docker Compose

Mount your local plugins/ directory into /app/plugins in your Docker Compose file:

services:
  kestra:
    image: kestra/kestra:v<version>-slim
    volumes:
      - ./plugins:/app/plugins

Restart the container after adding or removing JARs. Kestra loads plugins only at startup.

Verify the plugins

Confirm the plugins are present before you push or deploy the image:

docker run --rm kestra:custom-<version> \
  plugins list --plugins /app/plugins

For a Docker Compose mount, run the same check against the service instead:

docker compose run --rm --entrypoint /app/kestra kestra \
  plugins list --plugins /app/plugins

Both commands run the Kestra server CLI inside the container. For each plugin JAR found in /app/plugins, a line like the following appears in the output:

Found plugin on path: file:/app/plugins/io_kestra_storage__storage-s3__1_4_6.jar [Storages: io.kestra.storage.s3.S3FilesStorage, io.kestra.storage.s3.S3Storage]

On a running instance, kestractl plugins installed lists the plugins the server has loaded.

After you verify a custom image, tag it and push it to your registry:

docker tag kestra:custom-<version> my-registry.example.com/kestra:custom-<version>
docker push my-registry.example.com/kestra:custom-<version>

Alternative: install from inside the image

If you can’t run kestractl in your build environment, install plugins during the image build with the Kestra server CLI bundled in the image. Use kestra plugins install:

FROM kestra/kestra:v<version>-slim

RUN /app/kestra plugins install \
  io.kestra.plugin:plugin-dbt:LATEST \
  io.kestra.plugin:plugin-script-python:LATEST

This approach downloads from Maven Central at build time, so the build needs outbound network access. LATEST resolves to the newest version compatible with the image’s Kestra version.

Pin plugin versions in Enterprise

Open source Kestra loads one version of each plugin. Versioned Plugins in Kestra Enterprise let you install several versions side by side, pin a version per flow, and install or upgrade plugins from the UI without rebuilding the image.