Zellij Terminal Workspace Guide: Layouts, Panes, and the Modern Tmux Alternative

Zellij vs Tmux — What's Different?

Zellij is a modern terminal multiplexer written in Rust. Unlike tmux (which has a 30-year-old config syntax), Zellij uses KDL for configuration, has a built-in layout system, floating panes, and a plugin system — all out of the box.

This guide covers Zellij from installation to custom layouts and session management.

• Built-in multiplexer — no need for tmux
• Floating panes for temporary windows
• KDL-based layout files for reproducible workspace setups
• Session persistence and auto-restore

Installation & First Session

Install Zellij:

brew install zellij

• A modern terminal emulator (WezTerm, Kitty, Alacritty, or iTerm2)
• Rust toolchain optional (only if building from source)
• No prior multiplexer experience needed
• Zellij has sensible defaults — you can use it immediately

Layouts, Panes & Tabs

Run zellij to start a session. The interface shows a status bar at the bottom with key hints — you never need to memorize shortcuts.

• Ctrl+p — pane mode (split, move, resize)
• Ctrl+t — tab mode (new, close, switch)
• Ctrl+s — scroll/copy mode
• Ctrl+n — new pane (in pane mode)
• Ctrl+h / Ctrl+v — split horizontally/vertically
• Ctrl+d — detach session

Session Restore & Management

Layouts are Zellij's killer feature. Define a workspace as a KDL file and Zellij recreates it every time.

// ~/.config/zellij/layouts/dev.kdl
layout {
pane size=1 borderless {
plugin location="tab-bar"
}
pane split_direction="vertical" {
pane command="nvim"
pane split_direction="horizontal" {
pane command="npm" { args "run" "dev" }
pane command="npm" { args "run" "test" }
}
}
pane size=2 borderless {
plugin location="status-bar"
}
}

Launch with zellij --layout dev — your editor, dev server, and test runner all start at once.

• One layout per project — never set up panes manually again
• Floating panes: Ctrl+p + w creates a floating window for temporary work
• Session persistence: Zellij can auto-restore sessions on restart
• Plugin system: write panes in WASM

Floating Panes & Plugins

Advanced Zellij features:

• Custom themes in ~/.config/zellij/themes/
• Command panes: run a command, and if it exits, the pane closes automatically
• Stacked panes: overlay panes on top of each other and switch between them
• Keybinds mode: define custom keybindings that change based on context
• Compare with tmux: Zellij is easier to learn, tmux is more battle-tested

Layout Parsing Errors

Common Zellij issues:

• Layout not loading? Check KDL syntax — Zellij shows parse errors on launch
• Can't detach? Press Ctrl+o then d, or Ctrl+d depending on your version
• Session lost after reboot? Enable session serialization in config: session_serialization true
• Colors wrong? Set default_shell and ensure your terminal supports true color

Workspace Mastery

Zellij is set up. Explore more:

• Master KDL layouts (see [[Zellij Layouts and Floating Panes]])
• Compare with tmux (see [[Tmux Terminal Multiplexer Guide]])
• Pair with WezTerm for the ultimate terminal setup (see [[WezTerm Configuration Guide]])