WezTerm Horizontal/Vertical Split Shortcut on macOS

To enable horizontal and vertical splits in WezTerm on macOS, you must define custom keybindings in the wezterm.lua configuration file. The default configuration does not assign these shortcuts, so you need to explicitly map keys like Cmd+Shift+H for horizontal and Cmd+Shift+V for vertical splitting using the launch_split action.

Understanding WezTerm Configuration

WezTerm is highly configurable through a Lua script located at ~/.config/wezterm/wezterm.lua. Unlike many other terminal emulators that rely on hardcoded defaults or simple toggle switches, WezTerm requires explicit definition of actions and their associated key combinations. This approach provides flexibility but means that users cannot expect split functionality to work out of the box without adding specific lines to their configuration file. If you are new to configuring WezTerm, it is helpful to understand that the file is loaded every time the terminal starts. You do not need to restart the application manually after saving changes; WezTerm detects updates automatically. However, if your syntax is incorrect, the terminal may fail to launch or display errors in its log output. Always validate your Lua syntax before applying changes. For more complex configurations involving remote editing or advanced keymaps, understanding the underlying structure is crucial. See our guide on Vim/Nvim: Setting Up Remote Editing for a Project on a Remote Machine for insights into managing complex terminal workflows.

Editing the Configuration File

Open your terminal and navigate to the WezTerm configuration directory. If the file does not exist, create it using a text editor such as nano, vim, or your preferred GUI editor. mkdir -p ~/.config/wezterm nano ~/.config/wezterm/wezterm.lua Once opened, ensure you have the basic initialization code. Most configurations start by requiring the wezterm module and defining an initial configuration table. Your file should look similar to this foundation:

local wezterm = require 'wezterm'

return {
  -- Your configuration options go here
}

This structure is mandatory. Any additions must be placed inside the returned table. Do not place code outside this return statement, as it will not be processed by the terminal emulator.

Defining Split Actions

To create the shortcuts, you need to add two specific actions to the keys array within your configuration table. WezTerm provides built-in actions for splitting panes. You do not need to write custom scripts for this; the library handles the pane management logic. Add the following lines inside the main return table:

keys = {
  {
    key = 'H',
    mods = 'CMD|SHIFT',
    action = wezterm.action{SplitHorizontal={domain='CurrentPaneDomain'}},
  },
  {
    key = 'V',
    mods = 'CMD|SHIFT',
    action = wezterm.action{SplitVertical={domain='CurrentPaneDomain'}},
  },
}

Let's break down what each part does. The key field specifies which character triggers the action. Here, we use 'H' for Horizontal and 'V' for Vertical. The mods field defines the modifier keys required. On macOS, CMD|SHIFT translates to holding down Command and Shift simultaneously. The action field calls the specific WezTerm function to perform the split. SplitHorizontal divides the current pane into top and bottom sections, while SplitVertical divides it into left and right sections. The domain='CurrentPaneDomain' ensures that the split happens relative to the pane you are currently focused on, rather than affecting the entire window layout in unexpected ways. It is important to note that WezTerm does not use mouse-based splitting by default in most standard setups, nor does it reload configuration with F5. Relying on visual cues or keyboard shortcuts defined in the OS level rather than the app itself can lead to confusion. Ensure you are editing the correct file and that your syntax is valid Lua.

Alternative Key Combinations

Some users prefer different shortcuts to avoid conflicts with existing system commands. For example, you might choose CMD+B for vertical and CMD+D for horizontal. To change this, simply modify the key values in the table above. Be cautious when choosing common letters like 'C' or 'V' as they may conflict with copy and paste operations unless you also override those bindings. If you find yourself needing to manage multiple terminal sessions or connect to remote servers frequently, having efficient split navigation is vital. While this article focuses on local splitting, the principles of keybinding customization apply equally to remote workflows. For deeper insights into terminal automation, you might explore how others handle API integrations in their daily command line tasks, as discussed in Can Anyone Use Google API for MacOS Terminal Command Line?.

Verifying the Setup

After saving the wezterm.lua file, open a new instance of WezTerm. Try pressing Command+Shift+H. You should see the current pane divide horizontally. Press Command+Shift+V to split vertically. If nothing happens, check the WezTerm log for syntax errors. You can view logs by running wezterm debug-log in another terminal session or checking the console output if launched from a shell. Common issues include typos in the key names or missing commas between table entries. Lua is sensitive to syntax, so even a small error can prevent the configuration from loading. If you encounter persistent issues, try resetting your configuration to the minimal example provided earlier and gradually re-add your settings to isolate the problem.

Advanced Pane Navigation

Once you have created splits, navigating between them efficiently is just as important as creating them. WezTerm allows you to switch focus between panes using additional keybindings. You can add commands to move left, right, up, or down.

  {
    key = 'LeftArrow',
    mods = 'CTRL',
    action = wezterm.action{ActivatePaneDirection='Left'},
  },
  {
    key = 'RightArrow',
    mods = 'CTRL',
    action = wezterm.action{ActivatePaneDirection='Right'},
  },

Combining split creation with rapid navigation creates a powerful workflow for developers who need to monitor logs, run tests, and edit code simultaneously. This setup eliminates the need to constantly adjust window sizes or switch tabs manually.

Frequently Asked Questions

Why doesn't my config change take effect immediately?

WezTerm typically auto-reloads the configuration file upon saving. If it does not, ensure there are no syntax errors preventing the file from parsing. Check the debug log for specific error messages indicating where the syntax failed.

Can I use mouse clicks to split panes instead of keyboard shortcuts?

While WezTerm supports some mouse interactions, relying on them for splitting is not standard practice and may be disabled by default. It is recommended to stick to keyboard shortcuts for consistency and speed across different environments.

What if I want to close a split pane?

You can close the active pane by pressing Ctrl+D (or Cmd+D if mapped) to send the exit signal, or by using the CloseCurrentPane action in your keybindings. This removes the pane and redistributes space among remaining siblings.

Does this configuration work on Linux and Windows?

The Lua configuration file is cross-platform. However, the modifier keys differ. On Linux, use ALT|SHIFT or SUPER|SHIFT depending on your desktop environment. On Windows, use CTRL|SHIFT.

How do I reset my keybindings to default?

To revert to defaults, simply delete or comment out the keys array in your wezterm.lua file. WezTerm will then fall back to its internal default mappings for splitting and navigation.