---
title: "WezTerm Plugins"
aliases: [wezterm-plugin-system, wezterm-lua-plugins]
tags: [wezterm, plugins, lua, terminal, dotfiles]
sources: [raw/Plugins - Wez's Terminal Emulator.md]
created: 2026-04-17
updated: 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](https://github.com/michaelbrusegard/awesome-wezterm).

## Installing a Plugin

```lua
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

```lua
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|Debug Overlay]]

## 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

```lua
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:

```lua
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|WezTerm Config]] — Lua config structure and file locations
- [[wiki/dotfiles/wezterm-cli-reference|WezTerm CLI Reference]] — CLI subcommands including Debug Overlay
- [[wiki/dotfiles/wezterm-key-bindings|WezTerm Key Bindings]] — keybinding config where plugins often hook in
- [[wiki/dotfiles/wezterm-pane-to-lua|Pane to Lua]] — passing data to Lua, useful in plugin development

## Sources

- [WezTerm Plugins Docs](https://wezterm.org/config/plugins.html)
- Raw file: `raw/Plugins - Wez's Terminal Emulator.md`