119 lines
4.1 KiB
Markdown
119 lines
4.1 KiB
Markdown
---
|
|
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`
|