How to install Logstash plugins

Adding a Logstash plugin expands what a pipeline can read, transform, or write without replacing the base service. Installing the required plugin matters when a pipeline depends on an input, filter, codec, or output that is not already present, because Logstash fails pipeline compilation when the referenced plugin cannot be found.

Package-based Debian and RPM installs manage plugins with /usr/share/logstash/bin/logstash-plugin. Current release packages already bundle many common plugins, and some capabilities are delivered through integration packages instead of standalone gems, so the first task is to confirm whether the needed plugin is already available before running an install.

The plugin manager normally downloads gems from RubyGems.org, which means internet access, proxy variables, or an offline plugin pack can determine whether installation succeeds on the target host. Any newly installed plugin changes the runtime itself, so a syntax check for any pipeline that uses it and a full restart of logstash.service are still required before production pipelines can use the new component.

1. Check whether the required plugin is already available.

   $ sudo /usr/share/logstash/bin/logstash-plugin list --verbose logstash-output-syslog
   Using bundled JDK: /usr/share/logstash/jdk
   ERROR: No plugins found

   The example uses logstash-output-syslog. Replace it with the exact plugin name needed by the pipeline. If the command already returns the plugin or a matching integration package, skip the install step and move directly to configuration or validation.

   Current Logstash packages already bundle many common plugins, so the missing-plugin check is important before installing anything new.

2. Install the required plugin.

   $ sudo /usr/share/logstash/bin/logstash-plugin install logstash-output-syslog
   Using bundled JDK: /usr/share/logstash/jdk
   Validating logstash-output-syslog
   Resolving mixin dependencies
   Updating mixin dependencies logstash-mixin-normalize_config_support
   Bundler attempted to update logstash-mixin-normalize_config_support but its version stayed the same
   Installing logstash-output-syslog
   Installation successful

   Most installs need access to RubyGems.org. When the host uses a proxy, export http_proxy and https_proxy before running the command. On disconnected hosts, build an offline plugin pack on a connected staging server and install the pack instead of pulling gems directly from the internet.

   Installing a plugin changes the Logstash runtime for the whole instance, not only one pipeline.

3. Confirm the plugin now appears in the local inventory.

   $ sudo /usr/share/logstash/bin/logstash-plugin list | grep '^logstash-output-syslog$'
   Using bundled JDK: /usr/share/logstash/jdk
   logstash-output-syslog

   Use the same check with the exact plugin name after every install so the local inventory proves the plugin is registered before a pipeline references it.

4. If a pipeline already references the new plugin, test the configuration before restarting the service.

   $ sudo -u logstash /usr/share/logstash/bin/logstash --path.settings /etc/logstash --path.data /tmp/logstash-configtest --config.test_and_exit
   Using bundled JDK: /usr/share/logstash/jdk
   Configuration OK
   [2026-04-08T09:14:32,546][INFO ][logstash.runner          ] Using config.test_and_exit mode. Config Validation Result: OK. Exiting Logstash

   Run the syntax check only after the pipeline configuration actually contains the new plugin block. Otherwise the command proves only that the current pipeline set is still valid.

   Current Logstash 9.x packages refuse superuser runs by default. Use the logstash service account for this validation unless /etc/logstash/logstash.yml explicitly enables allow_superuser.

   Related: How to test a Logstash pipeline configuration

5. Restart the Logstash service so the new plugin is loaded into the running JVM.

   $ sudo systemctl restart logstash.service

   Installed plugins require a full service restart. config.reload.automatic can reload pipeline files, but it does not load newly installed plugin code without restarting logstash.service.

   Related: How to manage the Logstash service with systemctl in Linux
   Related: How to enable Logstash pipeline reloads

6. Confirm the Logstash service returned to an active state after the restart.

   $ sudo systemctl status logstash.service --no-pager --lines=0
   ● logstash.service - logstash
        Loaded: loaded (/usr/lib/systemd/system/logstash.service; enabled; preset: enabled)
        Active: active (running) since Tue 2026-04-08 09:15:14 UTC; 6s ago
      Main PID: 21844 (java)
         Tasks: 104 (limit: 28486)
        Memory: 1.1G (peak: 1.1G)
           CPU: 32.441s

   An active service confirms that Logstash accepted the installed plugin set and current configuration. The final proof is to run the pipeline that uses the plugin and verify its expected event flow or plugin-specific output.

   Related: How to manage the Logstash service with systemctl in Linux