Skip to main content

​
Overview

WezTerm’s plugin system allows you to extend functionality by loading Lua modules from external sources. Plugins can provide color schemes, custom key bindings, status bar widgets, and more.

​
Installing Plugins

Plugins are loaded using wezterm.plugin.require(): 
local wezterm = require 'wezterm'
local plugin = wezterm.plugin

local status = plugin.require('https://github.com/username/plugin-name')

​
Plugin Sources

Plugins can be loaded from:
  • GitHub repositories: https://github.com/username/repo
  • Git URLs: https://gitlab.com/username/repo.git
  • Local paths: file:///home/user/my-plugin

​
Example: Loading from GitHub

local wezterm = require 'wezterm'
local smart_splits = wezterm.plugin.require('https://github.com/mrjones2014/smart-splits.nvim')

​
Plugin Cache

Plugins are cached locally to avoid repeated downloads:
  • Linux/macOS: ~/.cache/wezterm/plugins/
  • Windows: %LOCALAPPDATA%\wezterm\plugins\

​
Clearing Plugin Cache

rm -rf ~/.cache/wezterm/plugins/

​
Creating Plugins

A basic plugin structure: 
my-plugin/
├── plugin/
│   └── init.lua
└── README.md

​
plugin/init.lua

local wezterm = require 'wezterm'

local M = {}

function M.apply_to_config(config)
  config.color_scheme = 'MyCustomScheme'
  
  config.colors = {
    foreground = '#e0e0e0',
    background = '#1a1a1a',
  }
end

return M

​
Using the Plugin

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

local my_plugin = wezterm.plugin.require('https://github.com/username/my-plugin')
my_plugin.apply_to_config(config)

return config

​
Example Plugins

​
Status Bar Plugin

-- plugin/init.lua
local wezterm = require 'wezterm'

local M = {}

function M.setup(config)
  wezterm.on('update-status', function(window, pane)
    local date = wezterm.strftime '%Y-%m-%d %H:%M:%S'
    window:set_right_status(wezterm.format {
      { Attribute = { Intensity = 'Bold' } },
      { Foreground = { Color = '#74c7ec' } },
      { Text = date },
    })
  end)
end

return M

​
Color Scheme Plugin

-- plugin/init.lua
local M = {}

M.colors = {
  nord = {
    foreground = '#d8dee9',
    background = '#2e3440',
    cursor_bg = '#d8dee9',
    cursor_border = '#d8dee9',
    cursor_fg = '#2e3440',
    selection_bg = '#4c566a',
    selection_fg = '#d8dee9',
    ansi = {
      '#3b4252', '#bf616a', '#a3be8c', '#ebcb8b',
      '#81a1c1', '#b48ead', '#88c0d0', '#e5e9f0',
    },
    brights = {
      '#4c566a', '#bf616a', '#a3be8c', '#ebcb8b',
      '#81a1c1', '#b48ead', '#8fbcbb', '#eceff4',
    },
  },
}

function M.apply_to_config(config, scheme_name)
  if M.colors[scheme_name] then
    config.colors = M.colors[scheme_name]
  end
end

return M

​
Plugin Best Practices

Version Your Plugins: Use Git tags to version your plugins for stability.
Document Configuration: Provide clear documentation for plugin configuration options.
Plugins execute arbitrary Lua code. Only install plugins from trusted sources.

​
Plugin Documentation Template

# My WezTerm Plugin

Description of what the plugin does.

## Installation

```lua
local wezterm = require 'wezterm'
local my_plugin = wezterm.plugin.require('https://github.com/username/my-plugin')

​
Configuration

my_plugin.setup({
  option1 = 'value1',
  option2 = 'value2',
})

​
Options

  • option1 - Description
  • option2 - Description

## Plugin Distribution

### Publishing on GitHub

1. Create a repository with the plugin structure
2. Add documentation in README.md
3. Tag releases with semantic versioning
4. Share the repository URL

### Loading Specific Versions

```lua
local plugin = wezterm.plugin.require('https://github.com/username/plugin@v1.0.0')

​
Debugging Plugins

Enable debug logging: 
config.debug_key_events = true
Check the WezTerm log for plugin errors: 
tail -f ~/.local/share/wezterm/wezterm.log

​
Advanced Plugin Features

​
Event Handlers

local M = {}

function M.setup()
  wezterm.on('window-config-reloaded', function(window, pane)
    window:toast_notification('WezTerm', 'Configuration reloaded!', nil, 3000)
  end)
end

return M

​
Custom Key Bindings

local M = {}

function M.apply_to_config(config)
  table.insert(config.keys, {
    key = 'Space',
    mods = 'LEADER',
    action = wezterm.action.ShowLauncher,
  })
end

return M

​
See Also