obsidian/wiki/dotfiles/wezterm-plugins.md

title	aliases	tags	sources	created	updated
WezTerm Plugins	wezterm-plugin-system wezterm-lua-plugins	wezterm plugins lua terminal dotfiles	raw/Plugins - Wez's Terminal Emulator.md	2026-04-17	2026-04-17

Overview

WezTerm plugins are Lua packages that extend the terminal with functionality not included in the core product. They are distributed and installed via Git URLs (HTTPS or file:// protocol).

A curated list of plugins is maintained at awesome-wezterm.

Installing a Plugin

local wezterm = require 'wezterm'
local a_plugin = wezterm.plugin.require 'https://github.com/owner/repo'

local config = wezterm.config_builder()
a_plugin.apply_to_config(config)

return config

• URL must use https:// or file:// protocol
• On first require, WezTerm clones the repo into its runtime directory (plugins/NAME)
• Default branch (main) is checked out

With Plugin Configuration

local myPluginConfig = { enable = true, location = 'right' }
a_plugin.apply_to_config(config, myPluginConfig)

Consult each plugin's README for available options.

Updating Plugins

Plugins are not auto-updated when the upstream repo changes.

• Run wezterm.plugin.update_all() to pull all plugin updates
• Can be called from the Lua REPL in the wiki/dotfiles/wezterm-cli-reference

Removing a Plugin

1. Find the plugin directory with wezterm.plugin.list() — returns an array with plugin_dir and url fields
2. Delete the directory at plugins/NAME inside the WezTerm runtime directory

Developing a Plugin

Minimal Structure

myPlugin/
└── plugin/
    └── init.lua   ← must export apply_to_config(config, ...)

init.lua must return a module with at least apply_to_config(config).

Local Development Workflow

local a_plugin = wezterm.plugin.require "file:///home/user/projects/myPlugin"

After any code change, run wezterm.plugin.update_all() to sync into the runtime directory.

Multi-Module Plugins

When a plugin spans multiple Lua files, update package.path to point at the plugin directory:

function findPluginPackagePath(myProject)
  local sep = package.config:sub(1, 1) == '\\' and '\\' or '/'
  for _, v in ipairs(wezterm.plugin.list()) do
    if v.url == myProject then
      return v.plugin_dir .. sep .. 'plugin' .. sep .. '?.lua'
    end
  end
end

package.path = package.path .. ';' .. findPluginPackagePath 'file:///path/to/myPlugin'

Forking and Modifying an Existing Plugin

1. Remove original plugin from WezTerm (delete its plugin_dir)
2. Fork and clone the repo locally
3. Optionally add upstream remote to track original changes
4. Create a feature branch, then make it the default: git symbolic-ref HEAD refs/heads/mybranch
5. Fix any hard-coded plugin_dir references in the plugin source
6. Load via file:// URL and use the standard dev workflow

Key Takeaways

• Plugins install via wezterm.plugin.require 'https://...' — clones into the runtime directory
• Pass a Lua table as second arg to apply_to_config for plugin-specific options
• Updates are manual — run wezterm.plugin.update_all() explicitly
• Removal = delete the folder reported by wezterm.plugin.list()
• Local file:// URLs enable plugin development without publishing to GitHub
• Multi-module plugins need package.path patched to find sibling .lua files
• To fork a plugin: remove → clone → make your branch the repo default → load via file://

Related Articles

• wiki/dotfiles/wezterm-config — Lua config structure and file locations
• wiki/dotfiles/wezterm-cli-reference — CLI subcommands including Debug Overlay
• wiki/dotfiles/wezterm-key-bindings — keybinding config where plugins often hook in
• wiki/dotfiles/wezterm-pane-to-lua — passing data to Lua, useful in plugin development

Sources

• WezTerm Plugins Docs
• Raw file: raw/Plugins - Wez's Terminal Emulator.md