Zellij Complete Guide 2026: The Modern Rust-Powered Terminal Workspace, Best tmux Alternative

What is Zellij?

Zellij is a modern terminal workspace written in Rust, positioned as the next-generation alternative to tmux and GNU Screen. Its core philosophy is "batteries included"—you get powerful terminal multiplexing capabilities right out of the box without needing complex configurations.

Why Do You Need Zellij?

If you frequently use the terminal for development, operations, or system administration, you're likely familiar with these scenarios:

• Running multiple services simultaneously (frontend, backend, database) and switching between different windows
• SSH connections to remote servers getting disconnected, causing all processes to terminate
• Wanting to save a complex working state and restore it directly next time
• Sharing terminal sessions with your team for debugging or code reviews

The traditional solutions are tmux or GNU Screen, but they have steep learning curves, bare-bones default configurations, and often require manually writing config files to unlock advanced features.

Zellij aims to solve these pain points:

Zellij vs tmux: Core Differences

1. User Friendliness: Zellij provides an intuitive UI (status bar, tab bar) by default, whereas tmux requires manual configuration to achieve similar effects.
2. Floating Panes: Zellij allows panes to "float" above others, perfect for monitoring commands (like top or htop) while working on other tasks.
3. Web Client: Zellij has a built-in web server, allowing you to access terminal sessions via a browser without extra tools.
4. Session Resurrection: After closing Zellij, you can reopen it and restore all previous panes, commands, and history—even across reboots.
5. Plugin Ecosystem: Zellij plugins are based on WebAssembly and can be written in Rust, Go, C, or any language that compiles to WASM, offering higher security.

Installing Zellij

Zellij supports Linux, macOS, and Windows (WSL). Here are several common installation methods:

Method 1: Official One-Click Install Script (Recommended)

# Bash/Zsh
bash <(curl -L https://zellij.dev/launch)

# Fish
bash (curl -L https://zellij.dev/launch | psub)

# PowerShell
irm https://zellij.dev/launch.ps1 | iex

This script automatically detects your OS and architecture, then downloads and installs the latest version of Zellij.

Method 2: Package Manager Installation

macOS (Homebrew):

brew install zellij

Linux (Ubuntu/Debian):

# Add APT repository
echo "deb [trusted=yes] https://dl.cloudsmith.io/public/zellij-org/releases/deb/debian any-version main" | sudo tee /etc/apt/sources.list.d/zellij.list
sudo apt update
sudo apt install zellij

Arch Linux:

sudo pacman -S zellij

Fedora:

sudo dnf install zellij

Method 3: Compile from Source

If you need to compile from source (e.g., for a custom build):

# Ensure Rust toolchain is installed
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Clone the repository
git clone https://github.com/zellij-org/zellij.git
cd zellij

# Compile and install
cargo install --path zellij

Verify Installation

zellij --version

It should output a version number like zellij 0.42.0.

Quick Start: Your First Zellij Session

Launching Zellij

Simply run in your terminal:

zellij

You'll see a brand new interface with a tab bar at the top and a status bar at the bottom. By default, Zellij creates a tab named "main" and a single terminal pane.

Basic Operations

All Zellij shortcuts start with Ctrl + g as the prefix (known as the "mode key"). Here are the most common operations:

Tip: Press Ctrl+g → ? anytime to view the full list of shortcuts.

Floating Panes

Floating panes are one of Zellij's signature features. They allow a pane to "float" above others without occupying fixed grid space.

Enable Floating Panes:

# Shortcut: Alt + f

Or via command mode:

Ctrl+g → : → toggle_floating_panes

Typical Use Cases:

# Run htop in a floating pane to monitor system resources
htop

# Track logs in another floating pane
tail -f /var/log/syslog

# Continue coding or executing other commands in the main pane

Floating panes can be dragged, resized, and even "pinned" to stay on top.

Stacked Panes

Stacked panes allow you to stack multiple panes vertically, saving horizontal space.

Create Stacked Panes:

# First create two normal panes, then:
Ctrl+g → : → toggle_stack

Switch Between Stacked Panes:

# Use arrow keys to switch up and down

Stacked panes are particularly suitable for: - Keeping multiple editor buffers accessible - Monitoring multiple command outputs without taking up too much screen space - Organizing workspaces by task or context

Session Management: Saving and Restoring Work States

Session Manager

Zellij has a powerful built-in session management feature, making it easy to switch between multiple work environments.

Open Session Manager:

Ctrl+g → w

This displays a visual session selection interface where you can: - View all running sessions - Create new sessions (with custom names) - Switch to background sessions - Restore previously exited sessions

Welcome Screen

When starting Zellij for the first time, you can use the welcome screen to get started quickly:

zellij -l welcome

The welcome screen provides a "start menu"-like interface where you can: - Visually select a session - Create a new session - Restore previously exited sessions

Session Resurrection

This is one of Zellij's most unique features: even if you close Zellij or restart your computer, you can restore your complete previous working state next time you open it, including:

• Layout and size of all panes
• Commands running in each pane
• Scroll history
• Environment variables and working directories

How to Restore:

# Start Zellij normally, then select the session to restore via the session manager
zellij
Ctrl+g → w → Select the previously exited session

Or specify directly at startup:

zellij attach <session-name>

This is incredibly useful for long-running tasks (like compiling, testing, or data processing)—even if you accidentally disconnect or reboot, you can continue seamlessly.

Layout Automation: Defining Your Development Environment

Zellij's layout system allows you to declaratively define your entire development environment using KDL (a human-readable configuration format).

What is a Layout?

A layout is a .kdl file that describes: - How many tabs there are - Which panes are in each tab - What command each pane runs - The size and position of panes - Whether floating or stacking is used

Simple Layout Example

Create a file named my-project.kdl:

layout {
    tab name="Backend" {
        pane split_direction="Vertical" {
            pane command="cargo" args=["run"]
            pane command="npm" args=["run", "dev"]
        }
    }
    tab name="Database" {
        pane command="psql" args=["-U", "postgres", "-d", "mydb"]
    }
}

Use the Layout:

zellij --layout my-project.kdl

This will automatically: 1. Create two tabs: "Backend" and "Database" 2. In the "Backend" tab, split vertically into two panes running cargo run and npm run dev respectively 3. In the "Database" tab, run the PostgreSQL client

Command Panes

Command panes are a unique Zellij feature that treats commands as "first-class citizens" rather than simple terminal output.

Features: - You can see the command's exit code - Press Enter to re-run the command - Can be set to "suspended" state, triggered manually on demand - Perfect for building commands, running tests, or starting dev servers

Using Command Panes in Layouts:

layout {
    tab name="Dev" {
        pane command="cargo" args=["test"] start_suspended=true
        pane command="cargo" args=["build"] start_suspended=true
    }
}

start_suspended=true means the command won't run automatically; you need to press Enter to trigger it manually. This is very useful for resource-intensive operations (like full builds) to avoid automatic execution every time the layout starts.

Edit Panes

Zellij allows you to open any pane's scroll buffer directly in your $EDITOR:

# In the current pane, press:
Ctrl+s → e

This opens the entire output of the current pane in your configured editor (vim, neovim, emacs, etc.), allowing you to: - Search, copy, and organize terminal output - Save output as a file - Share with team members

Web Client: Accessing Your Terminal in a Browser

Zellij has a built-in web server that allows you to access terminal sessions directly through a browser. This means: - No Terminal Installation Required: Access your Zellij session from any device with a browser - Remote Collaboration: Share sessions with team members for pair programming or debugging - Seamless Switching: Switch freely between terminal and browser; session state remains consistent

Enabling the Web Client

Start Zellij with the web server enabled:

zellij --server /tmp/zellij-server.sock

Or enable it in the configuration file:

// ~/.config/zellij/config.kdl
plugins {
    path "/usr/lib/zellij/plugins"
}

keybinds {
    shared {
        bind "Alt w" { SwitchToMode "WebClient"; }
    }
}

Accessing Sessions

Open in your browser:

http://localhost:8082

You can: - View all running sessions - Access specific sessions directly via URL: http://localhost:8082/my-session - Create read-only tokens so others can view but not operate your session

Remote Access

Zellij supports remote session access via HTTPS:

# Attach to a remote session from another machine
zellij attach https://my-server:8082/my-session

This doesn't require SSH tunnels or third-party tools, making it ideal for: - Remote debugging - Pair programming - Technical support

Plugin System: Extending Functionality with WebAssembly

The Zellij interface itself is composed of plugins, including: - Tab Bar - Status Bar - Session Manager - Welcome Screen - File Selector (Strider)

Developing Your Own Plugins

Zellij plugins are based on WebAssembly (WASM) and can be written in any language that compiles to WASM (Rust, Go, C, etc.). Rust has first-class support and a dedicated SDK.

Creating a Simple Rust Plugin:

# Install the Zellij plugin scaffolding tool
cargo install zellij-plugin-template

# Create a new project
zellij-plugin-template my-plugin

cd my-plugin

Generated project structure:

my-plugin/
├── Cargo.toml
├── src/
│   └── main.rs
└── plugin.yaml

Example Plugin Code (src/main.rs):

use zellij_sdk::{prelude::*, Command};

#[command(name = "my-plugin")]
fn main() {
    // Subscribe to Zellij events
    subscribe(&[EventType::KeyPress(Key::Char('x'))]);

    loop {
        match std::io::stdin().read_line() {
            Ok(line) => {
                if line.contains("KeyPress") {
                    // Handle key press event
                    println!("Received key press!");
                }
            }
            Err(_) => break,
        }
    }
}

Compile and Install:

# Compile to WASM
cargo build --target wasm32-wasip1 --release

# Copy to Zellij plugin directory
cp target/wasm32-wasip1/release/my_plugin.wasm ~/.local/share/zellij/plugins/

Load the Plugin in Configuration:

// ~/.config/zellij/config.kdl
plugins {
    path "~/.local/share/zellij/plugins"
}

pane_templates {
    template name="my-plugin-pane" {
        plugin location="file:~/.local/share/zellij/plugins/my_plugin.wasm"
    }
}

Popular Community Plugins

• Strider: Dynamic file system navigation with fuzzy search
• Configuration Screen: Interactive configuration management
• Multiple Pane Select: Batch operations on multiple panes

You can find more community plugins in the Zellij Plugin Repository.

Advanced Scripting: CLI Control

Zellij exposes a complete control interface via CLI commands, allowing you to build complex terminal workflows from shell scripts or external tools.

Conditionally Blocking Panes

# Block until the command exits successfully
zellij action new-pane --command "cargo test" --block-until-exit-success

# Block until the command exits with failure
zellij action new-pane --command "npm run build" --block-until-exit-failure

# Block until the command exits (regardless of success or failure)
zellij action new-pane --command "make" --block-until-exit

Failed commands can be retried interactively without losing your place in the script.

Real-time Pane Output Streaming

# Stream output from any pane to stdout in real-time
zellij subscribe pane-id-123

# Use JSON format for structured processing
zellij subscribe pane-id-123 --json

This is very useful for monitoring logs on remote servers or building automated pipelines.

Structured State Queries

# List all panes (JSON format)
zellij list-panes --json

# List all tabs
zellij list-tabs --json

# Get current session info
zellij session-info

These commands can be integrated into your CI/CD pipelines, monitoring scripts, or custom dashboards.

Practical Cases: Building Developer Workflows

Case 1: Full-Stack Development Environment

Create a layout file fullstack-dev.kdl:

layout {
    tab name="Frontend" {
        pane split_direction="Vertical" {
            pane command="npm" args=["run", "dev"]
            pane command="npm" args=["run", "storybook"]
        }
    }
    tab name="Backend" {
        pane split_direction="Horizontal" {
            pane command="cargo" args=["run"]
            pane command="cargo" args=["watch", "-x", "test"] start_suspended=true
        }
    }
    tab name="Database" {
        pane command="docker" args=["compose", "up"]
        pane command="psql" args=["-U", "postgres", "-d", "myapp"]
    }
    tab name="Monitoring" {
        pane floating=true command="htop"
        pane floating=true command="tail" args=["-f", "/var/log/app.log"]
    }
}

Launch:

zellij --layout fullstack-dev.kdl

This layout will automatically: 1. Create 4 tabs for Frontend, Backend, Database, and Monitoring 2. In the Frontend tab, split vertically to run the dev server and Storybook 3. In the Backend tab, split horizontally to run the app and test watcher 4. In the Database tab, start Docker Compose and the PostgreSQL client 5. In the Monitoring tab, float htop and log tracking

Case 2: Remote Server Debugging

Suppose you need to debug an issue on a remote server:

# SSH to the remote server
ssh user@remote-server

# Start a Zellij session
zellij -s debugging-session

# View logs in the first pane
tail -f /var/log/app/error.log

# Create a new pane to run diagnostic commands
Ctrl+g → n
dmesg | tail -20

# Create a floating pane to monitor system resources
Ctrl+g → Alt+f
htop

# Enable the web client so colleagues can view remotely
# (Requires pre-configured web server)

Then tell your colleague to visit https://remote-server:8082/debugging-session. They can see your terminal session in real-time and even assist with operations (if write permissions are granted).

Case 3: Data Science Workflow

Create a layout for a data science project data-science.kdl:

layout {
    tab name="Notebook" {
        pane command="jupyter" args=["lab", "--no-browser"]
    }
    tab name="Data Processing" {
        pane split_direction="Vertical" {
            pane command="python" args=["process_data.py"]
            pane command="watch" args=["-n", "5", "ls", "-lh", "output/"]
        }
    }
    tab name="Visualization" {
        pane command="python" args=["visualize.py"]
        pane floating=true command="eog" args=["output/chart.png"]
    }
}

FAQ and Troubleshooting

Q1: Can Zellij and tmux be used simultaneously?

A: Yes, but nesting them is not recommended. You can run Zellij inside tmux or vice versa, but this leads to shortcut conflicts and performance issues. It's better to choose one as your primary terminal multiplexer.

Q2: How do I migrate tmux configurations to Zellij?

A: Zellij doesn't have a direct tmux config converter, but you can: 1. Refer to Zellij's default configuration file 2. Map tmux's common features to Zellij's equivalents 3. Use Zellij's layout system to replace tmux scripts

Q3: How is Zellij's performance?

A: Written in Rust, Zellij performs excellently. In most scenarios, its memory footprint and CPU usage are comparable to tmux, and it even performs better in some benchmarks. For large sessions (dozens of panes), Zellij remains responsive.

Q4: How do I use the mouse in Zellij?

A: Zellij supports mouse operations by default: - Click panes to switch focus - Drag pane borders to resize - Scroll with the mouse wheel to browse history - Click tabs to switch

If the mouse isn't working, check if your terminal emulator has mouse support enabled, or confirm in Zellij's config:

// ~/.config/zellij/config.kdl
mouse_mode true

Q5: Does Zellij support Windows?

A: Zellij natively supports Windows (via WSL2 or PowerShell). You can install it on Windows using the official one-click script:

irm https://zellij.dev/launch.ps1 | iex

Summary

Zellij is a modern terminal workspace that inherits the power of tmux while providing a friendlier user experience and innovative features:

Core Advantages: - ✅ Out of the Box: No complex configuration needed; provides an intuitive UI by default - ✅ Floating/Stacked Panes: Flexible pane management for multitasking - ✅ Session Resurrection: Restores complete working state even after reboot - ✅ Web Client: Access terminals via browser, supporting remote collaboration - ✅ Plugin System: WebAssembly-based, secure and extensible - ✅ Layout Automation: Declaratively define development environments with KDL - ✅ CLI Scripting: Complete control interface for automated workflows

Who Is It For? - Developers: Need to run multiple services, tests, and monitoring tools simultaneously - Ops Engineers: Need to manage remote servers and long-running tasks - Data Scientists: Need to organize Jupyter Notebooks, data processing, and visualization workflows - Team Collaboration: Need to share terminal sessions for pair programming or debugging

Next Steps: - Read the Zellij Official Documentation - Explore Community Plugins - Join the Discord or Matrix community

If you're looking for a modern alternative to tmux, Zellij is definitely worth a try. Its gentle learning curve and powerful features can significantly boost your terminal productivity.