最高のターミナル環境を手に入れろ - WezTermカスタマイズ完全ガイド

TL;DR

WezTerm は Lua で設定できる GPU アクセラレーション対応ターミナル
タブを矢印型にカスタマイズ、透過・ぼかし効果も簡単に実装可能
Leader key 方式で tmux 風のペイン操作を実現
Workspace 機能でプロジェクトごとの環境を管理
Vim ライクなコピーモードで快適なテキスト選択

この記事の対象読者

iTerm2 から新しいターミナルへの移行を検討している人
WezTerm の設定方法を具体的に知りたい人
tmux 風のペイン操作をターミナル単体で実現したい人
Lua でカスタマイズできるターミナルに興味がある人

環境・前提条件

macOS (Sequoia 15.2)
Homebrew 導入済み
Nerd Fonts 導入済み（タブのアイコン表示に必要）

WezTerm とは

WezTerm は Rust で書かれた、GPU アクセラレーションに対応したクロスプラットフォームのターミナルエミュレータです。

主な特徴:

Lua での柔軟な設定: プログラマブルな設定ファイル
高速レンダリング: GPU を活用した滑らかな描画
豊富な機能: タブ、ペイン分割、Workspace、コピーモード
クロスプラットフォーム: macOS/Linux/Windows で同じ設定が使える

iTerm2 と比較した利点は、設定ファイルが Git で管理しやすく、コードベースでカスタマイズできる点です。

インストール手順

Step 1: Homebrew で WezTerm をインストール

nightly 版を推奨（最新機能が使えるため）:

brew install --cask wezterm@nightly

安定版を使いたい場合:

brew install --cask wezterm

Step 2: インストール確認

wezterm --version

バージョン情報が表示されれば成功です。

Step 3: 設定ファイルのディレクトリを作成

mkdir -p ~/.config/wezterm
cd ~/.config/wezterm

ディレクトリ構成

設定ファイルを分割して管理します:

~/.config/wezterm/
├── wezterm.lua       # メイン設定
└── keybinds.lua      # キーバインド定義

この構成により、キーバインドだけを編集したいときに見通しが良くなります。

Step 1: 基本設定

~/.config/wezterm/wezterm.lua を作成します。

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

-- 自動リロード（設定変更時に即反映）
config.automatically_reload_config = true

-- フォント設定
config.font_size = 12.0

-- 日本語入力（IME）を有効化
config.use_ime = true

-- 透過とぼかし効果
config.window_background_opacity = 0.3
config.macos_window_background_blur = 20

-- 背景色（グラデーション）
config.window_background_gradient = {
  colors = { "#000000" },
}

return config

ポイント:

window_background_opacity: 0〜1 で透明度を指定
macos_window_background_blur: 背景のぼかし強度（macOS 専用）
use_ime: true にしないと日本語入力が正しく動作しない

Step 2: タブのカスタマイズ

タブバーを矢印型にして、アクティブタブを色分けします。

----------------------------------------------------
-- Tab
----------------------------------------------------
config.window_decorations = "RESIZE"
config.show_tabs_in_tab_bar = true
config.hide_tab_bar_if_only_one_tab = true

config.window_frame = {
  inactive_titlebar_bg = "none",
  active_titlebar_bg = "none",
}

config.show_new_tab_button_in_tab_bar = false
config.show_close_tab_button_in_tabs = false

config.colors = {
  tab_bar = {
    inactive_tab_edge = "none",
  },
}

-- タブの形をカスタマイズ（矢印型、Nerd Fonts使用）
local SOLID_LEFT_ARROW = wezterm.nerdfonts.ple_lower_right_triangle
local SOLID_RIGHT_ARROW = wezterm.nerdfonts.ple_upper_left_triangle

wezterm.on("format-tab-title", function(tab, tabs, panes, config, hover, max_width)
  local background = "#5c6d74"
  local foreground = "#FFFFFF"
  local edge_background = "none"

  if tab.is_active then
    background = "#ae8b2d"
    foreground = "#FFFFFF"
  end

  local edge_foreground = background
  local title = "   " .. wezterm.truncate_right(tab.active_pane.title, max_width - 1) .. "   "

  return {
    { Background = { Color = edge_background } },
    { Foreground = { Color = edge_foreground } },
    { Text = SOLID_LEFT_ARROW },
    { Background = { Color = background } },
    { Foreground = { Color = foreground } },
    { Text = title },
    { Background = { Color = edge_background } },
    { Foreground = { Color = edge_foreground } },
    { Text = SOLID_RIGHT_ARROW },
  }
end)

ポイント:

SOLID_LEFT_ARROW / SOLID_RIGHT_ARROW: Nerd Fonts のアイコンを使用
アクティブタブは #ae8b2d（ゴールド系）、非アクティブは #5c6d74（グレー系）
タブタイトルの前後にスペースを入れて見やすく

Step 3: キーバインド設定

~/.config/wezterm/keybinds.lua を作成します。

Leader key の設定

まず wezterm.lua に Leader key を追加:

config.disable_default_key_bindings = true
config.keys = require("keybinds").keys
config.key_tables = require("keybinds").key_tables
config.leader = { key = "q", mods = "CTRL", timeout_milliseconds = 2000 }

Leader key 方式とは:

tmux のように、Ctrl+q を押した後に別のキーを押すことで機能を呼び出す方式です。これにより、既存のショートカットと競合しにくくなります。

基本的なキーバインド

keybinds.lua:

local wezterm = require("wezterm")
local act = wezterm.action

-- キーテーブルの状態をステータスバーに表示
wezterm.on("update-right-status", function(window, pane)
  local name = window:active_key_table()
  if name then
    name = "TABLE: " .. name
  end
  window:set_right_status(name or "")
end)

return {
  keys = {
    -- コマンドパレット
    { key = "p", mods = "SUPER", action = act.ActivateCommandPalette },

    -- Tab 操作
    { key = "Tab", mods = "CTRL", action = act.ActivateTabRelative(1) },
    { key = "Tab", mods = "SHIFT|CTRL", action = act.ActivateTabRelative(-1) },
    { key = "t", mods = "SUPER", action = act({ SpawnTab = "CurrentPaneDomain" }) },
    { key = "w", mods = "SUPER", action = act({ CloseCurrentTab = { confirm = true } }) },

    -- Tab の並び替え
    { key = "{", mods = "LEADER", action = act({ MoveTabRelative = -1 }) },
    { key = "}", mods = "LEADER", action = act({ MoveTabRelative = 1 }) },

    -- フルスクリーン
    { key = "Enter", mods = "ALT", action = act.ToggleFullScreen },

    -- コピー&ペースト
    { key = "c", mods = "SUPER", action = act.CopyTo("Clipboard") },
    { key = "v", mods = "SUPER", action = act.PasteFrom("Clipboard") },

    -- フォントサイズ調整
    { key = "+", mods = "CTRL", action = act.IncreaseFontSize },
    { key = "-", mods = "CTRL", action = act.DecreaseFontSize },
    { key = "0", mods = "CTRL", action = act.ResetFontSize },
  },
  key_tables = {},
}

ポイント:

SUPER = macOS では Cmd、Windows/Linux では Win
LEADER = 先ほど設定した Ctrl+q
Cmd+p でコマンドパレットを開いて全機能にアクセス可能

Step 4: Pane 操作（tmux 風の分割）

ペイン分割のキーバインドを追加します。

-- keybinds.lua の keys に追加

-- ペイン分割（tmux風）
{ key = "d", mods = "LEADER", action = act.SplitVertical({ domain = "CurrentPaneDomain" }) },
{ key = "r", mods = "LEADER", action = act.SplitHorizontal({ domain = "CurrentPaneDomain" }) },

-- ペインを閉じる
{ key = "x", mods = "LEADER", action = act({ CloseCurrentPane = { confirm = true } }) },

-- ペイン移動（Leader + h/j/k/l）
{ key = "h", mods = "LEADER", action = act.ActivatePaneDirection("Left") },
{ key = "j", mods = "LEADER", action = act.ActivatePaneDirection("Down") },
{ key = "k", mods = "LEADER", action = act.ActivatePaneDirection("Up") },
{ key = "l", mods = "LEADER", action = act.ActivatePaneDirection("Right") },

-- ペインのズーム（最大化/復元）
{ key = "z", mods = "LEADER", action = act.TogglePaneZoomState },

-- ペインリサイズモード起動
{ key = "s", mods = "LEADER", action = act.ActivateKeyTable({ name = "resize_pane", one_shot = false }) },

-- ペイン選択モード起動（タイムアウト付き）
{ key = "a", mods = "LEADER", action = act.ActivateKeyTable({ name = "activate_pane", timeout_milliseconds = 1000 }) },

リサイズモードの実装

-- keybinds.lua の key_tables に追加
key_tables = {
  resize_pane = {
    { key = "h", action = act.AdjustPaneSize({ "Left", 1 }) },
    { key = "j", action = act.AdjustPaneSize({ "Down", 1 }) },
    { key = "k", action = act.AdjustPaneSize({ "Up", 1 }) },
    { key = "l", action = act.AdjustPaneSize({ "Right", 1 }) },
    -- Enter でモード終了
    { key = "Enter", action = "PopKeyTable" },
  },
  activate_pane = {
    { key = "h", action = act.ActivatePaneDirection("Left") },
    { key = "j", action = act.ActivatePaneDirection("Down") },
    { key = "k", action = act.ActivatePaneDirection("Up") },
    { key = "l", action = act.ActivatePaneDirection("Right") },
  },
},

使い方:

Ctrl+q -> d で縦分割
Ctrl+q -> r で横分割
Ctrl+q -> h/j/k/l でペイン移動
Ctrl+q -> s -> h/j/k/l でサイズ調整（Enter で終了）
Ctrl+q -> z で現在のペインをフルスクリーン化

Step 5: Workspace 管理

プロジェクトごとに Workspace を切り替える機能です。

-- keybinds.lua の keys に追加

-- Workspace 一覧表示
{ key = "w", mods = "LEADER", action = act.ShowLauncherArgs({ flags = "WORKSPACES", title = "Select workspace" }) },

-- 現在の Workspace の名前を変更
{
  key = "$",
  mods = "LEADER",
  action = act.PromptInputLine({
    description = "Set workspace title:",
    action = wezterm.action_callback(function(window, pane, line)
      if line then
        wezterm.mux.rename_workspace(wezterm.mux.get_active_workspace(), line)
      end
    end),
  }),
},

-- 新しい Workspace を作成
{
  key = "W",
  mods = "LEADER|SHIFT",
  action = act.PromptInputLine({
    description = "Create new workspace:",
    action = wezterm.action_callback(function(window, pane, line)
      if line then
        window:perform_action(
          act.SwitchToWorkspace({
            name = line,
          }),
          pane
        )
      end
    end),
  }),
},

使い方:

Ctrl+q -> W で新しい Workspace を作成
Ctrl+q -> w で Workspace 一覧から切り替え
Ctrl+q -> $ で現在の Workspace 名を変更

Step 6: コピーモード（Vim 操作）

Vim ライクなキーバインドでテキストを選択できます。

-- keybinds.lua の keys に追加
{ key = "[", mods = "LEADER", action = act.ActivateCopyMode },

-- key_tables に copy_mode を追加
copy_mode = {
  -- カーソル移動
  { key = "h", mods = "NONE", action = act.CopyMode("MoveLeft") },
  { key = "j", mods = "NONE", action = act.CopyMode("MoveDown") },
  { key = "k", mods = "NONE", action = act.CopyMode("MoveUp") },
  { key = "l", mods = "NONE", action = act.CopyMode("MoveRight") },

  -- 単語移動
  { key = "w", mods = "NONE", action = act.CopyMode("MoveForwardWord") },
  { key = "b", mods = "NONE", action = act.CopyMode("MoveBackwardWord") },
  { key = "e", mods = "NONE", action = act.CopyMode("MoveForwardWordEnd") },

  -- 行頭/行末
  { key = "0", mods = "NONE", action = act.CopyMode("MoveToStartOfLine") },
  { key = "$", mods = "NONE", action = act.CopyMode("MoveToEndOfLineContent") },
  { key = "^", mods = "NONE", action = act.CopyMode("MoveToStartOfLineContent") },

  -- ジャンプ
  { key = "f", mods = "NONE", action = act.CopyMode({ JumpForward = { prev_char = false } }) },
  { key = "t", mods = "NONE", action = act.CopyMode({ JumpForward = { prev_char = true } }) },
  { key = "F", mods = "NONE", action = act.CopyMode({ JumpBackward = { prev_char = false } }) },
  { key = "T", mods = "NONE", action = act.CopyMode({ JumpBackward = { prev_char = true } }) },

  -- スクロール
  { key = "g", mods = "NONE", action = act.CopyMode("MoveToScrollbackTop") },
  { key = "G", mods = "NONE", action = act.CopyMode("MoveToScrollbackBottom") },
  { key = "d", mods = "CTRL", action = act.CopyMode({ MoveByPage = 0.5 }) },
  { key = "u", mods = "CTRL", action = act.CopyMode({ MoveByPage = -0.5 }) },

  -- 選択モード
  { key = "v", mods = "NONE", action = act.CopyMode({ SetSelectionMode = "Cell" }) },
  { key = "V", mods = "NONE", action = act.CopyMode({ SetSelectionMode = "Line" }) },
  { key = "v", mods = "CTRL", action = act.CopyMode({ SetSelectionMode = "Block" }) },

  -- コピー
  { key = "y", mods = "NONE", action = act.CopyTo("Clipboard") },

  -- コピーモード終了
  {
    key = "Enter",
    mods = "NONE",
    action = act.Multiple({ { CopyTo = "ClipboardAndPrimarySelection" }, { CopyMode = "Close" } }),
  },
  { key = "Escape", mods = "NONE", action = act.CopyMode("Close") },
  { key = "q", mods = "NONE", action = act.CopyMode("Close") },
},

使い方:

Ctrl+q -> [ でコピーモード起動
h/j/k/l で移動、w/b/e で単語移動
v で選択開始、V で行選択、Ctrl+v で矩形選択
y でコピー、Enter でコピーしてモード終了
q または Esc でモード終了

キーバインド一覧表

基本操作

キー	機能
`Cmd+p`	コマンドパレット
`Cmd+t`	新しいタブ
`Cmd+w`	タブを閉じる
`Ctrl+Tab`	次のタブ
`Ctrl+Shift+Tab`	前のタブ
`Alt+Enter`	フルスクリーン切替

Leader key 操作（Ctrl+q の後に押す）

キー	機能
`d`	縦分割
`r`	横分割
`x`	ペインを閉じる
`h/j/k/l`	ペイン移動
`z`	ペインをズーム
`s`	リサイズモード起動
`a`	ペイン選択モード（1秒タイムアウト）
`{` / `}`	タブを左/右に移動
`[`	コピーモード起動
`w`	Workspace 一覧
`W`	新しい Workspace 作成
`$`	Workspace 名変更

コピーモード（Ctrl+q -> [ で起動）

キー	機能
`h/j/k/l`	カーソル移動
`w/b/e`	単語移動
`0/$`	行頭/行末
`g/G`	先頭/末尾
`Ctrl+d/u`	半ページ下/上
`f/t`	前方ジャンプ
`F/T`	後方ジャンプ
`v`	文字選択
`V`	行選択
`Ctrl+v`	矩形選択
`y`	コピー
`Enter`	コピーして終了
`q` または `Esc`	モード終了

iTerm2 からの移行 Tips

Before / After

Before（iTerm2）:

設定は GUI で変更（バージョン管理しづらい）
ペイン分割は Cmd+D / Cmd+Shift+D
タブの見た目カスタマイズが限定的
Workspace 機能なし

After（WezTerm）:

設定はすべて Lua ファイル（Git 管理可能）
Leader key 方式で tmux ライクな操作
タブの形・色を自由にカスタマイズ
Workspace でプロジェクトごとに環境を切替

よく使う iTerm2 機能の WezTerm 対応

iTerm2	WezTerm
Cmd+D（縦分割）	Ctrl+q -> d
Cmd+Shift+D（横分割）	Ctrl+q -> r
Cmd+[（ペイン移動）	Ctrl+q -> h/j/k/l
Cmd+Enter（フルスクリーン）	Alt+Enter
プロファイル切替	Workspace 切替（Ctrl+q -> w）

注意点・ハマりポイント

1. Nerd Fonts がないとタブが文字化けする

タブに矢印が表示されず、四角い文字化けが出る場合:

brew install --cask font-hack-nerd-font

設定ファイルでフォントを指定:

config.font = wezterm.font("Hack Nerd Font")

2. IME が正しく動作しない

日本語入力時に変換候補が表示されない場合:

config.use_ime = true

を必ず設定する。

3. キーバインドが反応しない

Leader key を押しても何も起きない場合:

config.disable_default_key_bindings = true を設定しているか確認
Leader key のタイムアウト（2000ms）以内に次のキーを押す
wezterm show-keys コマンドで現在のキーバインドを確認

4. `require("keybinds")` が見つからない

keybinds.lua が wezterm.lua と同じディレクトリ（~/.config/wezterm/）にあるか確認。

まとめ

WezTerm は iTerm2 からの移行先として優れた選択肢です:

設定ファイルの Git 管理: チーム内で設定を共有しやすい
tmux 不要のペイン操作: Leader key 方式で快適
Workspace 機能: プロジェクトごとの環境切替がスムーズ
柔軟なカスタマイズ: Lua でタブ・キーバインドを自由に変更

特に、タブの矢印型カスタマイズや Vim ライクなコピーモードは、iTerm2 では実現が難しい WezTerm ならではの魅力です。

設定ファイルを段階的に拡張していくことで、自分だけの最適なターミナル環境を構築できます。

参考

タグ

WezTerm ターミナル iTerm2 Lua macOS