# Installing Zellij
**Zellij** is a modern terminal workspace and multiplexer written in Rust. It's designed as a tmux alternative with a focus on beginner-friendliness, out-of-the-box usability, and powerful features like floating panes, session management, and a WebAssembly plugin system.
## What Zellij Provides
- **Terminal multiplexing:** Multiple panes, tabs, and sessions in one terminal
- **Beautiful UI:** Built-in status bar and tab bar (implemented as WASM plugins)
- **Beginner-friendly:** Keybinding hints always visible, intuitive defaults
- **Floating panes:** Modern window-manager-style pane overlays
- **Layouts:** Define and save custom workspace configurations
- **Plugin system:** Extend functionality with WebAssembly plugins (Rust or other languages)
- **Session management:** Attach/detach from sessions, session resurrection
- **No configuration required:** Works great out of the box
## Zellij vs tmux
| Feature | tmux | Zellij |
|---------|------|--------|
| Learning curve | Steep (manual keybindings) | Gentle (on-screen hints) |
| Configuration | Required for good UX | Optional (great defaults) |
| Plugin system | TPM (bash scripts) | WASM (Rust, any WASM language) |
| Floating panes | No | Yes |
| UI | Minimal (needs plugins) | Beautiful out of box |
| Maturity | Very stable (20+ years) | Stable (active development) |
| Performance | Excellent | Excellent (Rust) |
**Key difference:** Zellij prioritizes **discoverability** - you can be productive immediately without memorizing keybindings or writing config files.
## Pre-Installation Checklist
✅ **Homebrew installed** (macOS package manager)
✅ **Ghostty terminal** (for optimal rendering and true color support)
✅ **Nerd Font installed** (for icons in Zellij's UI)
✅ **No tmux auto-start** (Zellij replaces tmux, they shouldn't run together)
## Installation Steps
### Step 1: Install Zellij via Homebrew
```bash
# Install Zellij
brew install zellij
# Verify installation
zellij --version
```
You should see the version number (e.g., `zellij 0.40.0`).
### Step 2: Install a Nerd Font (If Not Already Installed)
Zellij's UI uses icons that require a patched font:
```bash
# Install JetBrainsMono Nerd Font (recommended)
brew install --cask font-jetbrains-mono-nerd-font
```
**Configure Ghostty to use the Nerd Font:**
Edit your Ghostty config:
```bash
chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"
```
Add or update:
```
font-family = "JetBrainsMono Nerd Font"
font-size = 13
```
Apply changes:
```bash
chezmoi apply
```
Restart Ghostty.
### Step 3: First Launch
Start Zellij for the first time:
```bash
zellij
```
You'll see:
- **Tab bar** at the top showing your current tab
- **Status bar** at the bottom showing available keybindings
- **Welcome message** in the main pane
The status bar shows **context-sensitive keybindings** - press `Ctrl+p` to enter "Pane mode" and see pane management shortcuts.
### Step 4: Test Basic Functionality
Try these actions to verify everything works:
1. **Split horizontally:** Press `Alt+n` (creates pane below)
2. **Split vertically:** Press `Alt+N` (Shift+Alt+n, creates pane to the right)
3. **Navigate panes:** Press `Alt+h/j/k/l` (Vim-style navigation)
4. **Create new tab:** Press `Ctrl+t` then `n`
5. **Rename tab:** Press `Ctrl+t` then `r`, type name, press Enter
6. **Quit Zellij:** Press `Ctrl+q` (or type `exit` in all panes)
### Step 5: Update Brewfile
Add Zellij to your managed Homebrew packages:
```bash
# Regenerate Brewfile
brew bundle dump --file=~/Brewfile --force
# Add to chezmoi
chezmoi add ~/Brewfile
# Commit changes
cd ~/.local/share/chezmoi
git add Brewfile
git commit -m "Add zellij terminal multiplexer"
git push
```
See [[2. Managing Homebrew with Brewfile]] for full workflow details.
## Integrating with Ghostty
### Auto-Start Zellij on Ghostty Launch
**Option 1: Launch Zellij manually when needed**
The simplest approach - just run `zellij` when you want a multiplexed session:
```bash
zellij
```
Or attach to an existing session:
```bash
zellij attach session-name
```
**Option 2: Auto-start Zellij in specific Ghostty windows**
Configure Ghostty to launch Zellij for specific keybindings:
Edit Ghostty config:
```bash
chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"
```
Add custom keybindings:
```
# Launch new window with Zellij
keybind = ctrl+shift+z=new_window:zellij
# Or make it the default for new windows
# window-shell-integration = false
# command = zellij
```
**Option 3: Auto-start via shell rc file**
Add to your `~/.zshrc`:
```bash
# Auto-start Zellij if not already in a session
if command -v zellij &> /dev/null && [ -z "$ZELLIJ" ]; then
zellij
fi
```
**Recommended approach for transitioning from tmux:** Start with Option 1 (manual launch) while learning Zellij. Once comfortable, switch to Option 3 for auto-start.
### Disable tmux Auto-Start
If you currently auto-start tmux in your shell rc file, comment it out:
Edit your shell config:
```bash
chezmoi edit ~/.zshrc
```
Find and comment out tmux auto-start:
```bash
# OLD tmux auto-start (disabled for Zellij)
# if command -v tmux &> /dev/null && [ -z "$TMUX" ]; then
# tmux attach -t default || tmux new -s default
# fi
```
Apply changes:
```bash
chezmoi apply
source ~/.zshrc
```
### True Color and Font Rendering
Ghostty provides excellent support for Zellij:
- **24-bit true color:** Automatic (no config needed)
- **Font rendering:** Optimized for coding fonts with Nerd Font icons
- **Clipboard integration:** Cmd+C/Cmd+V work seamlessly
- **Cursor shapes:** Change based on mode (requires `shell-integration = true` in Ghostty)
## Configuration
Zellij works great with zero configuration, but you can customize it.
### Config File Location
Zellij's config lives at:
```
~/.config/zellij/config.kdl
```
Create it if it doesn't exist:
```bash
mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl
```
The config uses **KDL** (pronounced "cuddle"), a document language similar to JSON/YAML but more human-friendly.
### Essential Configuration Options
Edit `~/.config/zellij/config.kdl`:
```kdl
// Set default shell
default_shell "zsh"
// Simplified UI (hide tab bar if only one tab)
simplified_ui true
// Set theme
theme "catppuccin-mocha"
// Mouse mode
mouse_mode true
// Pane frames (borders around panes)
pane_frames true
// Copy on selection (like tmux)
copy_on_select true
// Scrollback buffer size
scrollback_editor "nvim"
```
### Managing Themes
Zellij includes several built-in themes. View available themes:
```bash
# List all themes
ls ~/.config/zellij/themes/
# Or check the default themes in the config dump
zellij setup --dump-config | grep -A 20 "themes"
```
Popular themes:
- `catppuccin-mocha` (dark, pastel)
- `tokyo-night` (dark, vibrant)
- `gruvbox-dark` (retro, warm)
- `nord` (cool blues)
- `dracula` (purple accents)
Set theme in `config.kdl`:
```kdl
theme "catppuccin-mocha"
```
### Custom Keybindings
Zellij uses **modes** (similar to vim) for keybindings. You can customize any binding:
```kdl
keybinds {
normal {
// Add custom keybinding in normal mode
bind "Ctrl g" { SwitchToMode "locked"; }
}
pane {
// Customize pane mode keybindings
bind "x" { CloseFocus; SwitchToMode "normal"; }
}
}
```
**Modes:**
- `normal` - Default mode (navigation, tabs)
- `pane` - Pane management (Ctrl+p to enter)
- `tab` - Tab management (Ctrl+t to enter)
- `resize` - Resize panes (Ctrl+n to enter)
- `move` - Move panes (Ctrl+h to enter)
- `scroll` - Scrollback mode (Ctrl+s to enter)
- `locked` - Disable all Zellij keybindings (Ctrl+g to enter/exit)
### Managing Config with chezmoi
Since Zellij config is important, track it with chezmoi:
```bash
# Add Zellij config to chezmoi
chezmoi add ~/.config/zellij/config.kdl
# Edit via chezmoi
chezmoi edit ~/.config/zellij/config.kdl
# Apply changes
chezmoi apply
# Commit to version control
cd ~/.local/share/chezmoi
git add dot_config/zellij/config.kdl
git commit -m "Add Zellij configuration"
git push
```
See [[1. chezmoi]] for full dotfile management workflow.
## Working with Layouts
Layouts are Zellij's way of defining custom workspace configurations (like tmux sessions with pre-defined panes).
### Default Layouts Location
```
~/.config/zellij/layouts/
```
### Creating a Layout
Create a layout file `~/.config/zellij/layouts/dev.kdl`:
```kdl
layout {
// Define a tab for editing
tab name="Editor" {
pane split_direction="vertical" {
pane {
// Full-height editor pane
}
pane split_direction="horizontal" size="30%" {
pane {
// Top-right terminal
}
pane {
// Bottom-right terminal
}
}
}
}
// Define a tab for servers
tab name="Servers" {
pane {
command "npm"
args "run" "dev"
}
}
}
```
### Using a Layout
Start Zellij with a specific layout:
```bash
zellij --layout dev
```
Or switch to a layout in a running session:
```bash
# Press Ctrl+p then 'l' to load a layout
```
### Example Layouts
**Three-column layout:**
```kdl
layout {
tab {
pane split_direction="vertical" {
pane size="33%"
pane size="34%"
pane size="33%"
}
}
}
```
**Editor + terminal + server:**
```kdl
layout {
tab name="Dev" {
pane split_direction="vertical" {
pane command="nvim"
pane split_direction="horizontal" size="40%" {
pane // Terminal
pane command="npm" args="run" "dev"
}
}
}
}
```
## Plugin System
Zellij has a **WebAssembly (WASM) plugin system** - plugins are compiled to WASM and run safely in Zellij's environment.
### How Plugins Work
- **Built-in UI components are plugins:** The tab bar and status bar are Rust plugins
- **Plugins are first-class citizens:** They can render UI, react to state changes, and control Zellij
- **Written in Rust** (or any language that compiles to WASM)
- **No separate plugin manager needed** - configure plugins directly in config or layouts
### Finding Plugins
Browse community plugins:
- **awesome-zellij:** https://github.com/zellij-org/awesome-zellij
- **Official examples:** https://zellij.dev/documentation/plugin-examples
Popular plugins:
- **zjstatus** - Customizable status bar with widgets
- **zellij-forgot** - Quick access to keybinding cheatsheet
- **room** - Session manager with quick switching
- **zellij-sessionizer** - fzf-based session creation from directories
### Installing a Plugin
Unlike tmux's TPM, Zellij plugins are configured directly in `config.kdl` or layouts.
**Example: Install zjstatus (custom status bar)**
1. Download the plugin WASM file:
```bash
mkdir -p ~/.config/zellij/plugins
cd ~/.config/zellij/plugins
curl -L https://github.com/dj95/zjstatus/releases/latest/download/zjstatus.wasm -o zjstatus.wasm
```
2. Configure it in `~/.config/zellij/config.kdl`:
```kdl
plugins {
zjstatus location="file:~/.config/zellij/plugins/zjstatus.wasm" {
format_left "{mode} {tabs}"
format_right "{datetime}"
mode_normal "NORMAL"
mode_locked "LOCKED"
datetime "#[fg=#6C7086,bold] {format} "
datetime_format "%Y-%m-%d %H:%M"
}
}
```
3. Use it in a layout:
```kdl
layout {
default_tab_template {
pane
pane size=1 borderless=true {
plugin location="zjstatus"
}
}
}
```
### Plugin Configuration in Layouts
Load plugins in specific panes:
```kdl
layout {
tab {
pane
pane size=1 borderless=true {
plugin location="file:~/.config/zellij/plugins/zjstatus.wasm"
}
}
}
```
**No TPM equivalent needed** - plugins are just files you reference in configs/layouts.
## Essential Keybindings
Zellij displays keybindings in the status bar. Here are the most common:
### Normal Mode (Default)
| Keybinding | Action |
|------------|--------|
| `Alt+n` | New pane below |
| `Alt+N` (Shift) | New pane to the right |
| `Alt+h/j/k/l` | Navigate panes (Vim-style) |
| `Alt+[/]` | Previous/next pane |
| `Ctrl+p` | Enter Pane mode |
| `Ctrl+t` | Enter Tab mode |
| `Ctrl+n` | Enter Resize mode |
| `Ctrl+s` | Enter Scroll mode |
| `Ctrl+o` | Enter Session mode |
| `Ctrl+g` | Enter Locked mode (disable Zellij keys) |
| `Ctrl+q` | Quit Zellij |
### Pane Mode (Ctrl+p)
| Keybinding | Action |
|------------|--------|
| `p` | Open pane in new tab |
| `n` | New pane below |
| `N` (Shift) | New pane to the right |
| `h/j/k/l` | Navigate panes |
| `f` | Toggle floating pane |
| `x` | Close focused pane |
| `r` | Rename pane |
| `z` | Toggle pane fullscreen |
| `Esc` | Back to normal mode |
### Tab Mode (Ctrl+t)
| Keybinding | Action |
|------------|--------|
| `n` | New tab |
| `x` | Close tab |
| `r` | Rename tab |
| `h/l` | Previous/next tab |
| `1-9` | Switch to tab by number |
| `Esc` | Back to normal mode |
### Session Mode (Ctrl+o)
| Keybinding | Action |
|------------|--------|
| `d` | Detach from session |
| `w` | Session manager (list sessions) |
| `Esc` | Back to normal mode |
**Pro tip:** The status bar always shows available keybindings for your current mode. You never need to memorize everything!
## Session Management
Zellij sessions persist in the background when you detach.
### Creating Named Sessions
```bash
# Create new session
zellij -s project-name
# Or
zellij --session project-name
```
### Listing Sessions
```bash
zellij list-sessions
# Or from within Zellij: Ctrl+o then 'w'
```
### Attaching to Sessions
```bash
# Attach to specific session
zellij attach project-name
# Attach to most recent session
zellij attach
```
### Deleting Sessions
```bash
zellij delete-session project-name
# Delete all sessions
zellij delete-all-sessions
```
### Session Resurrection
Unlike tmux, Zellij automatically saves session state. If Zellij crashes or your computer restarts, sessions can be restored:
```bash
# Zellij will prompt you to restore crashed sessions on next launch
zellij attach
```
## Troubleshooting
### Icons Not Displaying
**Problem:** Boxes or question marks instead of icons in the UI.
**Solution:**
1. Verify Nerd Font is installed: `brew list | grep font`
2. Check Ghostty config has the font: `chezmoi edit "Library/Application Support/com.mitchellh.ghostty/config"`
3. Ensure `font-family = "JetBrainsMono Nerd Font"`
4. Restart Ghostty
### Keybindings Not Working
**Problem:** Alt/Ctrl keybindings don't respond.
**Solution:**
1. Check if you're in Locked mode (Ctrl+g toggles this)
2. Verify Ghostty isn't capturing the keybindings
3. Try different keybinding modes (Ctrl+p, Ctrl+t, etc.)
### Zellij and tmux Conflict
**Problem:** Running both Zellij and tmux causes weird behavior.
**Solution:** Choose one multiplexer:
- **If using Zellij:** Disable tmux auto-start in `~/.zshrc`
- **If using tmux:** Don't launch Zellij inside tmux (or vice versa)
### Performance Issues
**Problem:** Zellij feels sluggish with many panes.
**Solution:**
1. Reduce scrollback buffer: Edit `config.kdl` → `scrollback_editor` settings
2. Disable mouse mode if not needed: `mouse_mode false`
3. Close unused panes/tabs
4. Check if a pane is running a resource-intensive process (htop, etc.)
### Copy/Paste Not Working
**Problem:** Can't copy text from Zellij panes.
**Solution:**
1. Enter Scroll mode: `Ctrl+s`
2. Use mouse to select text (if `mouse_mode true`)
3. Text is automatically copied to system clipboard
4. Paste with `Cmd+V` (macOS) or `Ctrl+Shift+V`
Alternatively, configure `copy_on_select true` in `config.kdl` for automatic copying.
## Migrating from tmux
If you're switching from tmux, here's a comparison:
| tmux | Zellij Equivalent |
|------|-------------------|
| `tmux new -s name` | `zellij -s name` |
| `tmux attach -t name` | `zellij attach name` |
| `tmux ls` | `zellij list-sessions` |
| `Ctrl+b %` (split vertical) | `Alt+N` |
| `Ctrl+b "` (split horizontal) | `Alt+n` |
| `Ctrl+b arrow` (navigate) | `Alt+h/j/k/l` |
| `Ctrl+b c` (new window) | `Ctrl+t n` |
| `Ctrl+b d` (detach) | `Ctrl+o d` |
| `.tmux.conf` | `~/.config/zellij/config.kdl` |
| TPM (plugin manager) | No manager needed (just config files) |
**Key workflow differences:**
- **tmux:** Prefix key (`Ctrl+b`) before every command
- **Zellij:** Modal system (enter mode, then single keys) OR Alt-based shortcuts
**Layouts vs Sessions:**
- **tmux sessions:** Defined via commands or tmuxinator/tmuxp
- **Zellij layouts:** KDL files in `~/.config/zellij/layouts/`
## Next Steps
1. **Learn the basics:** Use Zellij daily for a week to internalize keybindings
2. **Create a layout:** Define a custom workspace for your most common project
3. **Try plugins:** Install zjstatus or zellij-sessionizer to enhance your workflow
4. **Customize config:** Tweak themes, keybindings, and UI settings in `config.kdl`
5. **Version control:** Add Zellij config to chezmoi for portability
6. **Explore advanced features:** Floating panes, session manager, plugin development
## Links
### Zellij Official Documentation
- **URL:** https://zellij.dev/documentation/
- **Summary:** Complete documentation covering installation, usage, layouts, plugins, and configuration in KDL format.
- **Related:** [[1. tmux Basics]], [[Ghostty + tmux Startup Automation]], [[1. chezmoi]]
### awesome-zellij Plugin Repository
- **URL:** https://github.com/zellij-org/awesome-zellij
- **Summary:** Community-curated list of Zellij plugins, themes, and resources. Browse WASM plugins for status bars, session management, and integrations.
- **Related:** [[3. TPM - Tmux Plugin Manager]]
### Zellij Plugin System Documentation
- **URL:** https://zellij.dev/documentation/plugins
- **Summary:** Guide to writing and using WebAssembly plugins for Zellij in Rust or other WASM-compatible languages.
- **Related:** [[Rust]]
### KDL Configuration Language
- **URL:** https://kdl.dev/
- **Summary:** Documentation for KDL (pronounced "cuddle"), the human-friendly document language used for Zellij config files.
- **Related:** [[1. chezmoi]]