zellij-guide

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Zellij Guide — Personal Reference

Zellij 指南 — 个人参考

Binary:
/Users/wcygan/.nix-profile/bin/zellij
(installed via Nix flake) Config:
~/Development/dotfiles/config/zellij/config.kdl
→ symlinked to
~/.config/zellij/config.kdl
Layouts:
~/Development/dotfiles/config/zellij/layouts/
For exhaustive action/option/layout reference, see reference.md.

二进制文件:
/Users/wcygan/.nix-profile/bin/zellij
(通过Nix flake安装) 配置文件:
~/Development/dotfiles/config/zellij/config.kdl
→ 软链接至
~/.config/zellij/config.kdl
布局文件:
~/Development/dotfiles/config/zellij/layouts/
如需完整的操作/选项/布局参考,请查看reference.md

Quick Start

快速开始

bash
zellij                           # New session (random name)
zellij -s work                   # New named session
zellij -l dev                    # New session with dev.kdl layout
zellij ls                        # List sessions (including exited)
zellij a work                    # Attach to "work" session
zellij d work                    # Delete exited session

bash
zellij                           # 新建会话(随机名称)
zellij -s work                   # 新建命名会话
ezellij -l dev                    # 使用dev.kdl布局新建会话
zellij ls                        # 列出所有会话(包括已退出的)
zellij a work                    # 连接到“work”会话
ezellij d work                    # 删除已退出的会话

Your Keybinds (clear-defaults=true, vim-style)

你的快捷键设置(clear-defaults=true,Vim风格)

Your config uses
clear-defaults=true
— only these bindings exist:
你的配置使用
clear-defaults=true
— 仅以下快捷键生效:

Normal Mode (default)

普通模式(默认)

KeyAction
Ctrl h
Move focus / tab left
Ctrl l
Move focus / tab right
Ctrl j
Move focus down
Ctrl k
Move focus up
Ctrl n
New pane (auto direction)
Ctrl s
New pane down
Ctrl v
New pane right
Ctrl -
New pane down
Ctrl /
New pane right
Ctrl x
Close focused pane
Ctrl z
Toggle fullscreen
Ctrl t
New tab
Ctrl w
Close tab
Ctrl 1-5
Go to tab 1-5
Ctrl q
Quit
Ctrl d
Detach
Ctrl p
→ Pane mode
Ctrl r
→ Resize mode
Ctrl m
→ Move mode
Ctrl g
→ Locked mode
Ctrl b
→ Scroll mode
按键操作
Ctrl h
向左移动焦点/切换标签页
Ctrl l
向右移动焦点/切换标签页
Ctrl j
向下移动焦点
Ctrl k
向上移动焦点
Ctrl n
新建面板(自动方向)
Ctrl s
向下新建面板
Ctrl v
向右新建面板
Ctrl -
向下新建面板
Ctrl /
向右新建面板
Ctrl x
关闭当前焦点面板
Ctrl z
切换全屏模式
Ctrl t
新建标签页
Ctrl w
关闭标签页
Ctrl 1-5
切换到第1-5个标签页
Ctrl q
退出Zellij
Ctrl d
断开会话连接
Ctrl p
→ 面板模式
Ctrl r
→ 调整大小模式
Ctrl m
→ 移动面板模式
Ctrl g
→ 锁定模式
Ctrl b
→ 滚动模式

Pane Mode (
Ctrl p
to enter,
Esc
to exit)

面板模式(按
Ctrl p
进入,
Esc
退出)

KeyAction
h/j/k/l
Move focus
n
New pane
x
Close pane
f
Toggle fullscreen
w
Toggle floating panes
e
Toggle embed/float
r
Rename pane
按键操作
h/j/k/l
移动焦点
n
新建面板
x
关闭面板
f
切换全屏
w
切换浮动面板显示
e
切换嵌入/浮动模式
r
重命名面板

Resize Mode (
Ctrl r
to enter,
Esc
to exit)

调整大小模式(按
Ctrl r
进入,
Esc
退出)

KeyAction
h/j/k/l
Resize in direction
H/J/K/L
Increase in direction
=
Increase size
-
Decrease size
按键操作
h/j/k/l
向对应方向调整面板大小
H/J/K/L
向对应方向大幅调整面板大小
=
增大面板大小
-
减小面板大小

Move Mode (
Ctrl m
to enter,
Esc
to exit)

移动面板模式(按
Ctrl m
进入,
Esc
退出)

KeyAction
h/j/k/l
Move pane in direction
按键操作
h/j/k/l
向对应方向移动面板

Scroll Mode (
Ctrl b
to enter,
Esc
to exit)

滚动模式(按
Ctrl b
进入,
Esc
退出)

KeyAction
j/k
Scroll down/up
Ctrl d
/
Ctrl u
Half page down/up
g
Scroll to top
G
Scroll to bottom
按键操作
j/k
向下/向上滚动
Ctrl d
/
Ctrl u
向下/向上滚动半页
g
滚动到顶部
G
滚动到底部

Locked Mode (
Ctrl g
to toggle)

锁定模式(按
Ctrl g
切换)

All keys pass through to the terminal. Only
Ctrl g
exits.
所有按键直接传递给终端。仅按
Ctrl g
可退出该模式。

Modes NOT configured (from defaults)

未配置的默认模式

Your config does not define:
tab
,
search
,
entersearch
,
renametab
,
renamepane
,
session
,
tmux
. Consider adding
search
and
session
modes for search-in-scrollback and session manager access.

你的配置未定义以下模式:
tab
search
entersearch
renametab
renamepane
session
tmux
。建议添加
search
session
模式,以支持回滚搜索和会话管理功能。

Your Config Summary

你的配置摘要

kdl
// Key settings in config.kdl:
default_layout "compact"          // 1-line compact-bar (tab + status combined)
pane_frames false                 // No borders between panes
theme "default"                   // Base16 dark theme (defined inline)
default_shell "~/.nix-profile/bin/fish"
copy_on_select true
scrollback_editor "/usr/bin/nvim"
session_serialization true        // Enable resurrection
serialize_pane_viewport true      // Save visible content
max_panes 100
layout_dir "~/.config/zellij/layouts"
Note:
default_shell
and
layout_dir
use
/home/wcygan/
paths (Linux). On macOS these should be
/Users/wcygan/
paths. Consider using
$HOME
or updating for cross-platform use.

kdl
// config.kdl中的关键设置:
default_layout "compact"          // 单行紧凑栏(标签页+状态栏合并)
pane_frames false                 // 面板之间无边框
theme "default"                   // Base16深色主题(内联定义)
default_shell "~/.nix-profile/bin/fish"
copy_on_select true
scrollback_editor "/usr/bin/nvim"
session_serialization true        // 启用会话恢复功能
serialize_pane_viewport true      // 保存面板可见内容
max_panes 100
layout_dir "~/.config/zellij/layouts"
注意
default_shell
layout_dir
使用的是Linux路径
/home/wcygan/
。在macOS上应改为
/Users/wcygan/
路径。建议使用
$HOME
以实现跨平台兼容。

Your Layouts

你的布局文件

dev.kdl (3-tab development layout)

dev.kdl(3标签页开发布局)

Tab "main" (focused):
┌─────────────────────┬──────────┐
│                     │ terminal │
│  editor (70%)       ├──────────┤
│                     │  logs    │
└─────────────────────┴──────────┘

Tab "git":     lazygit (full pane)
Tab "monitor": btop (50%) + services (50%)
Load with:
zellij -l dev
or
zellij --layout ~/.config/zellij/layouts/dev.kdl

标签页 "main"(默认焦点):
┌─────────────────────┬──────────┐
│                     │ terminal │
│ 编辑器(占70%)       ├──────────┤
│                     │ 日志面板    │
└─────────────────────┴──────────┘

标签页 "git":     lazygit(全屏面板)
标签页 "monitor": btop(占50%)+ 服务面板(占50%)
加载方式:
zellij -l dev
zellij --layout ~/.config/zellij/layouts/dev.kdl

Modes Reference (13 total)

模式参考(共13种)

ModePurposeYour binding
normal
Default operations(default)
locked
Pass-through (safety)
Ctrl g
pane
Pane management
Ctrl p
resize
Resize panes
Ctrl r
move
Move panes
Ctrl m
scroll
Scroll buffer
Ctrl b
tab
Tab management(not bound)
search
Search in scrollback(not bound)
entersearch
Type search query(not bound)
renametab
Rename a tab(not bound)
renamepane
Rename a pane(not bound)
session
Session management(not bound)
tmux
tmux compatibility(not bound)

模式用途你的快捷键绑定
normal
默认操作模式(默认进入)
locked
按键直通模式(安全用途)
Ctrl g
pane
面板管理
Ctrl p
resize
调整面板大小
Ctrl r
move
移动面板
Ctrl m
scroll
滚动缓冲区
Ctrl b
tab
标签页管理(未绑定)
search
回滚内容搜索(未绑定)
entersearch
输入搜索关键词(未绑定)
renametab
重命名标签页(未绑定)
renamepane
重命名面板(未绑定)
session
会话管理(未绑定)
tmux
Tmux兼容模式(未绑定)

CLI Quick Reference

CLI 快速参考

Session Management

会话管理

bash
zellij                                    # New session
zellij -s <name>                          # Named session
zellij ls                                 # List all (running + exited)
zellij attach <name>                      # Attach / resurrect
zellij attach -c <name>                   # Create-or-attach
zellij kill-session <name>                # Kill running session
zellij delete-session <name>              # Delete exited session
zellij kill-all-sessions                  # Kill all
zellij delete-all-sessions                # Delete all exited
bash
zellij                                    # 新建会话
zellij -s <name>                          # 新建命名会话
zellij ls                                 # 列出所有会话(运行中+已退出)
zellij attach <name>                      # 连接/恢复会话
zellij attach -c <name>                   # 连接或新建会话
zellij kill-session <name>                # 终止运行中的会话
zellij delete-session <name>              # 删除已退出的会话
zellij kill-all-sessions                  # 终止所有会话
zellij delete-all-sessions                # 删除所有已退出的会话

Run Commands in Panes

在面板中运行命令

bash
zellij run -- htop                        # New pane running htop
zellij run -f -- htop                     # Floating pane
zellij run -f --width 80% --height 80% -- htop  # Sized floating
zellij run -i -- make build               # In-place (replaces current pane)
zellij run -c -- make test                # Close pane on exit
zellij run -s -- dangerous-cmd            # Start suspended (ENTER to run)
zellij run -n "build" -- make             # Named pane
bash
zellij run -- htop                        # 新建运行htop的面板
zellij run -f -- htop                     # 新建浮动面板运行htop
zellij run -f --width 80% --height 80% -- htop  # 新建指定大小的浮动面板运行htop
zellij run -i -- make build               # 在当前面板中运行(替换当前面板内容)
zellij run -c -- make test                # 命令执行完成后自动关闭面板
zellij run -s -- dangerous-cmd            # 新建暂停状态的面板(按ENTER后运行命令)
zellij run -n "build" -- make             # 新建命名为“build”的面板

Edit Files

编辑文件

bash
zellij edit src/main.rs                   # Open in $EDITOR pane
zellij edit -f src/main.rs                # Floating editor pane
zellij edit -l 42 src/main.rs             # Open at line 42
bash
zellij edit src/main.rs                   # 在$EDITOR面板中打开文件
zellij edit -f src/main.rs                # 在浮动编辑器面板中打开文件
zellij edit -l 42 src/main.rs             # 打开文件并定位到第42行

Actions (from outside or within)

操作命令(外部或内部执行)

bash
zellij action new-pane                    # New pane
zellij action new-pane --floating         # New floating pane
zellij action new-tab --name "build"      # Named new tab
zellij action go-to-tab 2                 # Switch to tab 2
zellij action dump-layout                 # Export current layout to stdout
zellij action dump-screen /tmp/out.txt    # Dump pane content
zellij action switch-mode locked          # Enter locked mode
zellij action toggle-floating-panes       # Toggle floats
zellij action rename-session "work"       # Rename session
bash
zellij action new-pane                    # 新建面板
zellij action new-pane --floating         # 新建浮动面板
zellij action new-tab --name "build"      # 新建命名为“build”的标签页
zellij action go-to-tab 2                 # 切换到第2个标签页
zellij action dump-layout                 # 将当前布局导出到标准输出
zellij action dump-screen /tmp/out.txt    # 导出面板内容到文件
zellij action switch-mode locked          # 进入锁定模式
zellij action toggle-floating-panes       # 切换浮动面板显示状态
zellij action rename-session "work"       # 重命名会话

Setup Utilities

设置工具

bash
zellij setup --dump-config                # Print default config
zellij setup --dump-layout default        # Print default layout
zellij setup --dump-layout compact        # Print compact layout
zellij setup --dump-swap-layout default   # Print swap layout
zellij setup --generate-completion fish   # Fish completions
zellij setup --generate-auto-start fish   # Auto-start script
zellij setup --check                      # Validate config
bash
zellij setup --dump-config                # 打印默认配置
zellij setup --dump-layout default        # 打印默认布局
zellij setup --dump-layout compact        # 打印紧凑布局
zellij setup --dump-swap-layout default   # 打印交换布局
zellij setup --generate-completion fish   # 生成Fish shell补全脚本
zellij setup --generate-auto-start fish   # 生成自动启动脚本
zellij setup --check                      # 验证配置文件有效性

Convenience Aliases (from shell completions)

便捷别名(来自shell补全)

AliasExpands to
zr
zellij run --
zrf
zellij run --floating --
ze
zellij edit

别名展开命令
zr
zellij run --
zrf
zellij run --floating --
ze
zellij edit

Session Resurrection

会话恢复

Your config has resurrection enabled (
session_serialization true
,
serialize_pane_viewport true
).
What's saved: Layout, pane structure, commands, visible viewport, scrollback. What's NOT saved: Running processes. Commands show "Press ENTER to run..." on resurrection.
bash
zellij ls                                 # Shows EXITED sessions
zellij attach <exited-session>            # Resurrect it
zellij attach <name> --force-run-commands # Skip ENTER confirmation
zellij delete-session <name>              # Permanently remove
Serialized sessions are human-readable KDL layout files in the cache directory. They can be shared, modified, or loaded directly with
zellij --layout
.

你的配置已启用会话恢复功能(
session_serialization true
serialize_pane_viewport true
)。
保存的内容:布局、面板结构、命令、面板可见视口、回滚缓冲区。 不保存的内容:运行中的进程。恢复会话后,命令会显示“按ENTER键运行...”。
bash
zellij ls                                 # 查看已退出的会话
zellij attach <exited-session>            # 恢复已退出的会话
zellij attach <name> --force-run-commands # 跳过ENTER确认直接恢复运行命令
zellij delete-session <name>              # 永久删除已退出的会话
序列化的会话是缓存目录中的可读KDL布局文件。这些文件可以共享、修改,或通过
zellij --layout
直接加载。

Floating & Stacked Panes

浮动与堆叠面板

Floating:
Ctrl p
then
w
(toggle),
e
(embed/float), or
Alt f
(if default binds) Pinned floating: Always-on-top panes (pin via CLI:
zellij run -f --pinned -- cmd
) Stacked: Panes in a stack where only the focused one is expanded. Define in layouts with
stacked=true
.

浮动面板:按
Ctrl p
然后按
w
(切换显示)、
e
(切换嵌入/浮动),或使用默认快捷键
Alt f
(如果未修改默认绑定) 固定浮动面板:始终显示在顶层的面板(通过CLI创建:
zellij run -f --pinned -- cmd
堆叠面板:仅当前焦点面板展开的堆叠式面板。在布局文件中通过
stacked=true
定义。

Plugins (Built-in)

内置插件

PluginLocationDescription
tab-bar
zellij:tab-bar
Tab bar (1 line)
status-bar
zellij:status-bar
Status bar with keybind hints (2 lines)
compact-bar
zellij:compact-bar
Combined tab+status (1 line)
strider
zellij:strider
File browser sidebar
session-manager
zellij:session-manager
Session switcher + resurrection UI
filepicker
zellij:strider
File picker (cwd based)
configuration
zellij:configuration
Runtime config editor
plugin-manager
zellij:plugin-manager
Plugin management UI
Load in layouts:
kdl
pane size=1 borderless=true {
    plugin location="zellij:compact-bar"
}

插件位置描述
tab-bar
zellij:tab-bar
标签页栏(单行)
status-bar
zellij:status-bar
带快捷键提示的状态栏(两行)
compact-bar
zellij:compact-bar
合并标签页+状态栏的紧凑栏(单行)
strider
zellij:strider
文件浏览器侧边栏
session-manager
zellij:session-manager
会话切换器+恢复UI
filepicker
zellij:strider
基于当前目录的文件选择器
configuration
zellij:configuration
运行时配置编辑器
plugin-manager
zellij:plugin-manager
插件管理UI
在布局文件中加载插件:
kdl
pane size=1 borderless=true {
    plugin location="zellij:compact-bar"
}

Troubleshooting

故障排查

IssueFix
macOS Alt key not workingConfigure in terminal app (iTerm2: Profiles → Keys → Left Option = Esc+)
Copy not workingAdd
copy_command "pbcopy"
to config
Font/character issuesUse Nerd Font or
simplified_ui true
Ctrl+H triggers Move modeTerminal sends Ctrl+H as backspace — remap in terminal or Zellij
Nesting preventionCheck
$ZELLIJ
env var before starting
Mouse selectionHold SHIFT to bypass Zellij mouse capture
Styled underline colors wrongAdd
styled_underlines false
Config not loadingCheck
zellij setup --check
and verify path
问题解决方法
macOS上Alt键无效在终端应用中配置(iTerm2:配置文件 → 按键 → 左Option键 = Esc+)
复制功能无效在配置文件中添加
copy_command "pbcopy"
字体/字符显示异常使用Nerd Font或设置
simplified_ui true
Ctrl+H触发移动模式终端将Ctrl+H识别为退格键 — 在终端或Zellij中重新映射快捷键
防止嵌套启动启动前检查
$ZELLIJ
环境变量
鼠标选择按住SHIFT键绕过Zellij的鼠标捕获
样式化下划线颜色错误添加
styled_underlines false
到配置文件
配置文件未加载运行
zellij setup --check
验证并检查路径是否正确

Fish Shell Integration

Fish Shell 集成

fish
undefined
fish
undefined

Nesting prevention (add to config.fish or conf.d/)

防止嵌套启动(添加到config.fish或conf.d/目录下)

if status is-interactive; and not set -q ZELLIJ zellij attach -c default end
if status is-interactive; and not set -q ZELLIJ zellij attach -c default end

Generate completions

生成补全脚本

zellij setup --generate-completion fish > ~/.config/fish/completions/zellij.fish
undefined
zellij setup --generate-completion fish > ~/.config/fish/completions/zellij.fish
undefined

Environment Variables

环境变量

VariableDescription
ZELLIJ
Set to
0
inside a session (use for nesting prevention)
ZELLIJ_SESSION_NAME
Current session name
ZELLIJ_CONFIG_DIR
Override config directory
ZELLIJ_CONFIG_FILE
Override config file
ZELLIJ_AUTO_ATTACH
Auto-attach to existing session
ZELLIJ_AUTO_EXIT
Exit shell when Zellij exits

变量描述
ZELLIJ
在Zellij会话内会被设为
0
(用于防止嵌套启动)
ZELLIJ_SESSION_NAME
当前会话名称
ZELLIJ_CONFIG_DIR
覆盖默认配置目录
ZELLIJ_CONFIG_FILE
覆盖默认配置文件
ZELLIJ_AUTO_ATTACH
自动连接到现有会话
ZELLIJ_AUTO_EXIT
当Zellij退出时自动关闭shell

Layout Authoring Quick Reference

布局编写快速参考

kdl
layout {
    // Tab template applied to all tabs
    default_tab_template {
        pane size=1 borderless=true { plugin location="zellij:tab-bar" }
        children    // ← where tab content goes
        pane size=2 borderless=true { plugin location="zellij:status-bar" }
    }

    tab name="code" focus=true {
        pane split_direction="vertical" {
            pane size="60%" name="editor" edit="src/main.rs"
            pane size="40%" split_direction="horizontal" {
                pane name="term"
                pane name="test" command="make" { args "test"; }
            }
        }
    }

    tab name="git" {
        pane command="lazygit"
    }

    // Floating panes section
    floating_panes {
        pane x="10%" y="10%" width="80%" height="80%" name="scratch"
    }
}
kdl
layout {
    // 应用于所有标签页的默认标签页模板
    default_tab_template {
        pane size=1 borderless=true { plugin location="zellij:tab-bar" }
        children    // ← 标签页内容的插入位置
        pane size=2 borderless=true { plugin location="zellij:status-bar" }
    }

    tab name="code" focus=true {
        pane split_direction="vertical" {
            pane size="60%" name="editor" edit="src/main.rs"
            pane size="40%" split_direction="horizontal" {
                pane name="term"
                pane name="test" command="make" { args "test"; }
            }
        }
    }

    tab name="git" {
        pane command="lazygit"
    }

    // 浮动面板区域
    floating_panes {
        pane x="10%" y="10%" width="80%" height="80%" name="scratch"
    }
}

Key layout attributes

布局关键属性

AttributeApplies toValues
split_direction
pane
"vertical"
,
"horizontal"
size
pane
"50%"
or fixed int (lines/cols)
command
paneCommand to execute
args
child of command pane
"arg1" "arg2"
edit
paneFile path (opens in $EDITOR)
cwd
pane, tab, layoutWorking directory
name
pane, tabDisplay name
focus
pane, tab
true
for initial focus
borderless
pane
true
to hide frame
close_on_exit
paneClose when command exits
start_suspended
paneWait for ENTER
stacked
paneStack children
plugin location
child blockPlugin URL
CWD composes: pane cwd → tab cwd → layout cwd → execution directory. Relative paths chain; absolute paths override.
For the full actions reference, theme system, swap layouts, and plugin configuration, see reference.md.
属性适用对象取值
split_direction
面板
"vertical"
"horizontal"
size
面板
"50%"
或固定数值(行数/列数)
command
面板要执行的命令
args
命令面板的子属性
"arg1" "arg2"
edit
面板要打开的文件路径(在$EDITOR中打开)
cwd
面板、标签页、布局工作目录
name
面板、标签页显示名称
focus
面板、标签页
true
表示默认焦点
borderless
面板
true
表示隐藏边框
close_on_exit
面板命令执行完成后自动关闭面板
start_suspended
面板新建暂停状态的面板
stacked
面板堆叠子面板
plugin location
面板子块插件URL
工作目录优先级:面板cwd → 标签页cwd → 布局cwd → 执行Zellij时的目录。相对路径会继承,绝对路径会覆盖。
如需完整的操作参考、主题系统、交换布局和插件配置,请查看reference.md