Posted on:July 31, 2026 at 12:00 AM

Zellij 시작하기: 터미널 워크스페이스 친절 가이드

Zellij 시작하기: 터미널 워크스페이스 친절 가이드

Zellij 시작하기: 터미널 워크스페이스 친절 가이드

Zellij란?

Zellij는 터미널 멀티플렉서입니다. tmux나 GNU screen과 같은 카테고리죠. 한 번 실행해두면 그 안에서 페인(화면 분할), , 그리고 터미널을 닫아도 계속 살아 있는 세션을 쓸 수 있습니다.

핵심은 태그라인에 그대로 담겨 있습니다. “a terminal workspace with batteries included” — 배터리 포함 터미널 워크스페이스. tmux가 빈 화면과 설정 파일을 던져주는 것과 달리, Zellij는 지금 쓸 수 있는 단축키를 상태 표시줄에 계속 보여주고, 세션 매니저·파일 브라우저·플러그인 시스템을 기본 탑재한 채로, 첫 실행부터 쓸모 있는 일을 해줍니다.

Rust로 작성된 오픈소스(MIT)이고, 0.44부터는 Linux·macOS·Windows에서 모두 네이티브로 동작합니다.

이 글에서 다루는 내용:

  1. Zellij 설치
  2. 첫 5분 — 실제로 필요한 것만
  3. 페인, 탭, 그리고 모드 시스템
  4. 세션: 분리(detach), 재연결, 재부팅 후 복구
  5. 설정(config.kdl)과 무난한 시작 설정
  6. 레이아웃 — 프로젝트 작업 환경을 한 번 정의해두고 계속 쓰기
  7. CLI로 Zellij를 스크립트에서 조종하기
  8. 브라우저로 세션 공유하기
  9. tmux에서 넘어오는 분들을 위한 노트

1. 설치

macOS

brew install zellij

Linux

Arch(pacman -S zellij), Alpine(apk add zellij), Nix(nix-env -iA nixpkgs.zellij)는 최신 버전을 패키지로 제공합니다. Debian, Ubuntu, Fedora는 이 글을 쓰는 시점 기준으로 패키지가 없으니 정적 바이너리를 받으세요:

curl -L https://github.com/zellij-org/zellij/releases/latest/download/zellij-x86_64-unknown-linux-musl.tar.gz \
  | tar xz
sudo mv zellij /usr/local/bin/

Rust가 있는 모든 플랫폼

cargo install --locked zellij

cargo install은 소스에서 컴파일하므로 몇 분 걸립니다. 기다리기 싫다면 cargo binstall zellij로 미리 빌드된 바이너리를 받으면 됩니다.

Windows

0.44부터 릴리스 페이지에 네이티브 Windows 바이너리가 올라옵니다. 압축을 풀고 PowerShell이나 Windows Terminal에서 zellij.exe를 실행하면 됩니다.

확인

zellij --version
zellij setup --check   # Zellij가 사용하는 config/layout/data 디렉터리를 출력

zellij setup --check는 지금 한 번 실행해볼 만합니다. Zellij가 설정 파일을 어디서 찾는지 정확히 알려주기 때문에 나중에 헷갈릴 일이 줄어듭니다(macOS는 경로가 다릅니다. 아래에서 자세히).

2. 첫 5분

그냥 실행하세요:

zellij

페인 하나에, 위에는 탭 바, 아래에는 상태 표시줄이 있는 화면이 뜹니다. 이 상태 표시줄이 사실상 튜토리얼 전부입니다. 사용 가능한 모드를 나열해주고, 모드에 들어가면 그 안의 키를 보여줍니다. 첫날부터 뭔가를 외울 필요가 없습니다. 그냥 아래 바를 읽으면 됩니다.

바로 해볼 만한 네 가지:

동작
새 페인Alt n
페인 간 이동Alt h / j / k / l (또는 방향키)
새 탭Ctrl t 다음 n
분리(계속 실행된 채로 나가기)Ctrl o 다음 d

분리한 뒤 zellij attach를 실행하면 나갔던 그 자리로 돌아옵니다.

가장 먼저 알아야 할 함정: Ctrl q종료입니다. 확인 없이 세션과 그 안의 모든 것을 죽입니다. Ctrl o 다음 d분리로, 전부 살려둔 채 빠져나옵니다. 다른 것보다 이 차이를 먼저 익히세요.

3. 페인, 탭, 모드

모드 시스템

Zellij가 “아, 이런 거구나” 하고 이해되는 지점이 바로 이겁니다. tmux처럼 프리픽스 키 한 번에 명령 하나를 실행하는 대신, Zellij는 모드를 씁니다. Ctrl + 알파벳으로 모드에 들어가고, 그 안에서는 알파벳만 눌러 동작시키고, EnterEsc로 Normal 모드로 돌아옵니다.

모드진입 키용도
PaneCtrl p분할, 닫기, 전체화면, 플로팅, 이름 변경
TabCtrl t생성, 닫기, 이름 변경, 번호로 이동
ResizeCtrl n포커스된 페인 크기 조절
MoveCtrl h레이아웃 안에서 페인 위치 이동
ScrollCtrl s스크롤백, 검색, 히스토리 편집
SessionCtrl o분리, 세션 매니저, 설정, 공유
LockedCtrl g모든 키를 앱으로 그대로 전달
TmuxCtrl btmux 호환 키 바인딩

현재 모드의 키를 상태 표시줄이 항상 보여주므로, 실제 사용 흐름은 이렇습니다. Ctrl + 뭔가를 누르고, 바를 읽고, 알파벳을 누른다.

Pane 모드 (Ctrl p)

n   새 페인               f   전체화면 토글
d   아래로 분할            w   플로팅 페인 토글
r   오른쪽으로 분할         e   포커스된 페인 플로팅 ↔ 고정 전환
s   스택형 페인 생성        i   플로팅 페인 고정(항상 위)
x   페인 닫기              c   페인 이름 변경
h/j/k/l  포커스 이동       z   페인 프레임 토글

Tab 모드 (Ctrl t)

n   새 탭                 1-9  N번 탭으로 이동
x   탭 닫기               Tab  최근 두 탭 토글
r   탭 이름 변경           b    페인을 별도 탭으로 분리
s   이 탭의 모든 페인에 입력 동기화

s(sync)는 작지만 유용합니다. 한 번 타이핑하면 탭 안 모든 페인에 동일하게 입력됩니다. SSH 세션 네 개에 같은 명령을 돌릴 때 편합니다.

Scroll 모드 (Ctrl s)

j/k 또는 ↑/↓   한 줄 이동        s   검색
Ctrl f/b       페이지 이동        e   스크롤백을 $EDITOR로 열기
d/u            반 페이지 이동     Ctrl c   맨 아래로

압권은 Ctrl s 다음 e입니다. 페인의 스크롤백을 통째로 $EDITOR에 넣어줍니다. 산더미 같은 빌드 로그를 익숙한 에디터에서 검색하고 복사하고 저장할 수 있습니다.

모든 모드에서 동작하는 단축키

모드 전환 없이 바로 쓰는 키들입니다:

Alt n         새 페인
Alt h/j/k/l   포커스 이동 (가장자리에서 Alt h/l은 탭 전환)
Alt f         플로팅 페인 토글
Alt +/-       포커스된 페인 크기 조절
Alt [ / ]     스왑 레이아웃 순환
Ctrl g        잠금 / 해제
Ctrl q        종료 (주의)

Alt [Alt ]는 과소평가된 기능입니다. Zellij에는 미리 정의된 배치가 들어 있는데, 이걸 순환시키면 지금 열려 있는 페인들이 알아서 재배치됩니다. 손으로 크기를 조절할 일이 거의 없어집니다.

플로팅 페인과 스택형 페인

tmux에는 없는 두 가지 페인 타입입니다.

플로팅 페인(Alt f)은 레이아웃 위에 창처럼 떠 있습니다. 숨겨진 상태에서도 계속 실행되므로 긴 빌드, docker compose logs -f, 잠깐 쓸 셸을 두기에 좋습니다. Ctrl p 다음 e로 플로팅 ↔ 타일 전환이 됩니다.

스택형 페인(Ctrl p 다음 s)은 페인들을 목록처럼 쌓아두고 한 번에 하나만 펼쳐서 보여줍니다. 여덟 개를 열어놨는데 가로 공간이 없을 때, 각각을 12칸짜리 조각으로 쪼개는 대신 방향키로 전부 접근할 수 있게 해줍니다.

마우스

마우스 지원은 기본으로 켜져 있습니다. 클릭으로 페인·탭 포커스, 경계 드래그로 크기 조절, Ctrl+드래그로 플로팅 페인 이동, Ctrl+스크롤로 포커스된 페인 크기 조절. 또 출력에서 파일 경로를 인식해서, 클릭하면 플로팅 페인에 에디터로 열어줍니다. 경로에 줄 번호가 있으면 그 줄로 바로 이동합니다.

4. 세션

세션은 탭과 페인을 담는 컨테이너입니다. 백그라운드 서버 프로세스에서 돌아가기 때문에 터미널을 닫아도(또는 SSH 연결이 끊겨도) 죽지 않습니다.

# 이름 있는 세션 시작
zellij -s myproject

# 실행 중인 세션 목록
zellij ls

# 연결 — 이름을 주거나, 생략하면 가장 최근 세션
zellij attach myproject
zellij attach

# 없으면 만들면서 연결 (셸 alias로 쓰기 좋음)
zellij attach -c myproject

# 정리
zellij kill-session myproject
zellij kill-all-sessions

분리는 Ctrl o 다음 d. 세션 안에서 Ctrl o 다음 w를 누르면 세션 매니저가 열립니다. 실행 중이든 아니든 모든 세션을 검색 가능한 목록으로 보여주고, 셸로 나가지 않고 바로 전환할 수 있습니다.

세션 부활(resurrection)

Zellij는 기본적으로 세션이 종료된 뒤에도 그 구조를 기억합니다. 탭, 페인, 작업 디렉터리, 실행 중이던 명령까지요. 죽은 세션에 attach하면 배치가 그대로 복원되고, 명령 페인은 일시정지 상태로 돌아오므로 Enter를 눌러 다시 실행하면 됩니다.

재부팅까지 견디게 하려면 설정에서 직렬화를 켜세요:

session_serialization true
serialize_pane_viewport true   // 화면에 있던 내용까지 복원
scrollback_lines_to_serialize 10000

tmux-resurrect 플러그인 조합이 아니라, 설정 한 줄입니다.

오래된 죽은 세션 정리:

zellij delete-session old-thing
zellij delete-all-sessions -y

셸 시작 시 자동 연결

모든 터미널 창이 같은 세션으로 들어가게 하려면 ~/.zshrc에 추가하세요:

eval "$(zellij setup --generate-auto-start zsh)"

bash나 fish는 해당 셸 이름을 쓰면 됩니다. 동작을 조정하고 싶으면 ZELLIJ_AUTO_ATTACH, ZELLIJ_AUTO_EXIT 환경 변수를 사용할 수 있습니다.

5. 설정

Zellij는 KDL로 설정합니다. 중괄호를 쓰고 쉼표가 없는, JSON을 좀 더 깔끔하게 만든 느낌의 설정 언어입니다.

파일 위치

zellij setup --check
  • Linux: ~/.config/zellij/config.kdl
  • macOS: ~/Library/Application Support/org.Zellij-Contributors.Zellij/config.kdl

여러 머신에서 dotfiles를 동기화한다면 macOS 경로가 성가십니다. 셸 프로파일에 ZELLIJ_CONFIG_DIR=~/.config/zellij를 export하면 양쪽 플랫폼이 같은 위치를 씁니다.

주석이 전부 달린 기본 설정을 덤프해서 출발점으로 삼으세요:

mkdir -p ~/.config/zellij
zellij setup --dump-config > ~/.config/zellij/config.kdl

변경을 보려고 재시작할 필요는 없습니다. Zellij가 설정 파일을 감시하다가 대부분의 설정을 바로 적용합니다. 세션 안에서 Ctrl o 다음 c를 누르면 설정 UI가 열리고, 거기서 바꾸면 파일에 대신 써줍니다.

무난한 시작 설정

// ~/.config/zellij/config.kdl

theme "catppuccin-mocha"

// "compact"는 탭 바를 숨기고 상태 표시줄을 한 줄로 줄입니다.
// 키에 익숙해진 뒤에는 작업 공간이 그만큼 넓어집니다.
default_layout "compact"

// 시스템 클립보드로 복사 (macOS. Linux는 wl-copy 또는 xclip)
copy_command "pbcopy"

// 마우스로 텍스트를 선택하면 즉시 복사
copy_on_select true

// 재부팅에도 살아남기
session_serialization true
serialize_pane_viewport true
scrollback_lines_to_serialize 10000

scroll_buffer_size 50000

// 페인 안에서 Zellij 세션이 돌아갈 때(예: SSH) 어떻게 처리할지.
// "ask"는 물어보고, "descend"는 포커스되면 항상 안쪽 세션에 키를 넘깁니다.
nested_session_handling "ask"

keybinds {
    // 일부 터미널에서 Alt+n이 충돌합니다. 대체 바인딩을 하나 더 둡니다.
    normal {
        bind "Alt Enter" { NewPane; }
    }
}

테마는 수십 개가 기본 내장되어 있습니다. zellij setup --dump-config에 목록이 나오고, 설정 UI(Ctrl o 다음 c)에서 실시간으로 미리 볼 수 있습니다.

페인 프레임 끄기

페인마다 둘러진 테두리는 페인당 두 행, 두 열을 잡아먹습니다. Ctrl p 다음 z로 토글할 수 있고, 설정에 pane_frames false를 넣으면 영구히 꺼집니다. copy_on_select를 켜고 프레임을 끄면 Zellij가 눈에 띄게 조용해집니다.

6. 레이아웃: 프로젝트 작업 환경 자동화

값어치를 확실히 하는 기능입니다. 레이아웃은 탭·페인·작업 디렉터리·명령을 기술한 KDL 파일입니다. zellij --layout dev 한 번이면 작업 환경 전체가 그대로 재구성됩니다.

최소 예제:

layout {
    pane
    pane split_direction="vertical" {
        pane
        pane command="htop"
    }
}

웹 프로젝트용 실전 예제:

layout {
    cwd "."

    // 이게 없으면 탭에 탭 바/상태 표시줄이 안 나옵니다.
    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 split_direction="vertical" {
        pane size="65%" name="editor" {
            command "nvim"
            args "."
        }
        pane split_direction="horizontal" {
            pane name="shell"
            pane name="git" {
                command "git"
                args "status"
                close_on_exit false
            }
        }
    }

    tab name="servers" {
        pane name="dev server" {
            command "npm"
            args "run" "dev"
            // 일시정지 상태로 뜹니다. Enter를 눌러야 실제로 시작됩니다.
            start_suspended true
        }
        pane name="tests" {
            command "npm"
            args "test" "--" "--watch"
            start_suspended true
        }
    }

    tab name="files" {
        pane {
            plugin location="zellij:strider"
        }
    }
}

↓ zellij-dev-layout.kdl 다운로드

~/.config/zellij/layouts/dev.kdl에 넣고 실행하세요:

zellij --layout dev

layouts 디렉터리 안에 있으면 이름만으로 참조됩니다. 경로를 직접 줄 수도 있고(zellij --layout ./team-layout.kdl), URL도 됩니다. 원격 레이아웃에 명령이 들어 있으면 Zellij가 실행 전에 확인을 요청합니다.

알아둘 만한 속성 세 가지:

  • start_suspended true — 명령이 준비만 되고 실행되지는 않은 상태로 페인이 생성됩니다. Enter를 눌러야 시작합니다. 항상 띄워둘 필요는 없는 개발 서버에 딱 맞습니다.
  • close_on_exit false — 명령이 끝나도 페인이 종료 코드를 보여주며 남고, Enter로 재실행됩니다. Zellij에서 명령 페인은 “뭔가 입력된 셸”이 아니라 일급 개념입니다.
  • default_tab_template — 커스텀 레이아웃은 기본 레이아웃을 통째로 대체합니다. 바(bar)까지 포함해서요. 탭이 휑하게 뜬다면 이게 원인입니다.

이미 세션 안에서 zellij --layout dev를 실행하면 새 세션 대신 현재 세션에 해당 탭들이 추가됩니다. 새 세션을 강제하려면 zellij --new-session-with-layout dev를 쓰세요.

“이 레포에 새로 온 사람을 어떻게 온보딩하지?”에 대한 답이 레이아웃입니다. 레이아웃 파일을 커밋해두면 새 팀원이 당신과 똑같은 작업 환경을 그대로 받습니다.

스왑 레이아웃

Alt [Alt ]는 스왑 레이아웃을 순환합니다. 지금 열린 페인들을 미리 정의된 배치로 다시 흘려 넣는 기능이죠. 레이아웃 파일 옆에 직접 정의할 수도 있지만(dev.swap.kdl), 기본 제공되는 것만으로도 대부분 충분합니다. 요점은 손으로 크기를 조절할 일이 대개 없다는 것입니다.

7. CLI로 조종하기

UI가 하는 일은 거의 전부 명령으로도 됩니다. tmux가 어정쩡하게 지원하던 스크립트 자동화가 Zellij에서는 제대로 됩니다.

# 새 페인에서 명령 실행
zellij run -- cargo test

# 플로팅 페인에서
zellij run --floating -- docker compose logs -f

# 방향과 이름을 지정해서
zellij run --direction down --name "server" -- npm run dev

# 새 페인에서 $EDITOR로 파일 열기, 줄 번호 지정
zellij edit src/main.rs --line-number 42

# 현재 세션에 액션 보내기
zellij action new-tab --name "deploy"
zellij action go-to-tab 2
zellij action write-chars "echo hello"
zellij action dump-screen /tmp/pane.txt

# 바깥에서 세션을 이름으로 지정
zellij --session myproject action new-pane

셸 자동완성을 설정하면 자주 쓰는 세 가지 alias가 딸려 옵니다:

# zsh — ~/.zshrc에 추가
eval "$(zellij setup --generate-completion zsh)"
zr cargo watch -x test      # 새 페인에서 실행
zrf htop                    # 플로팅 페인에서 실행
ze src/main.rs              # 새 페인에서 편집

0.44부터 스크립트 자동화가 눈에 띄게 좋아졌습니다. 명령이 생성한 페인 ID를 반환하고, --blocking--block-until-exit-success로 페인 안의 명령이 끝날 때까지 스크립트를 기다리게 할 수 있으며, zellij action list-paneszellij subscribe로 상태를 조회하거나 페인 출력을 JSON으로 stdout에 스트리밍할 수 있습니다. 셸 스크립트만으로 “페인을 띄우고, 기다리고, 결과에 따라 반응하는” 실제 파이프라인을 짤 수 있다는 뜻입니다.

8. 브라우저로 세션 공유하기

Zellij에는 웹 서버가 내장되어 있습니다. 기본은 꺼져 있고, 켜면 어떤 세션이든 북마크 가능한 고정 URL로 브라우저에서 열 수 있습니다.

# 웹 서버 시작 (기본 127.0.0.1:8082)
zellij web --start

# 상태 확인 / 중지
zellij web --status
zellij web --stop

# 로그인 토큰 생성
zellij web --create-token --token-name laptop

# 보기만 하고 입력은 못 하는 읽기 전용 토큰
zellij web --create-read-only-token

항상 켜두려면 설정에:

web_server true
web_sharing "on"
web_server_ip "127.0.0.1"
web_server_port 8082

의식적으로 챙겨야 할 두 가지:

  • localhost 밖으로 바인딩하려면 TLS가 필요합니다. 네트워크에 노출한다면 web_server_certweb_server_key를 설정하세요. 인증 없는 터미널을 0.0.0.0에 올리면 안 됩니다.

  • 페어링에는 읽기 전용 공유가 안전한 기본값입니다. zellij watch <session>은 터미널에서 읽기 전용으로 붙고, Ctrl o 다음 s는 브라우저 토큰을 만드는 공유 플러그인을 엽니다.

    0.44에는 SSH 터널 없이 터미널에서 바로 원격 세션에 붙는 기능도 추가됐습니다:

zellij attach https://example.com/my-cool-session

9. tmux에서 넘어온다면

손가락이 이미 tmux를 기억한다면 Ctrl b를 눌러보세요. tmux 모드로 들어가서 ", %, c, ,, n, p, d, z, x, 방향키가 기대한 대로 동작합니다. 완전한 에뮬레이션은 아니고 다리 역할이지만, 첫 일주일이 훨씬 편해집니다.

실질적인 차이는 이렇습니다:

tmuxZellij
기능 발견man 페이지를 읽는다상태 표시줄을 읽는다
설정.tmux.conf, 적용하려면 재시작config.kdl, 핫 리로드
작업 환경 구성tmuxinator / 셸 스크립트레이아웃 내장
세션 복원tmux-resurrect 플러그인설정 한 줄
플로팅 페인팝업 (제한적)일급, 지속됨
플러그인셸 스크립트WebAssembly, 언어 무관
브라우저 접근내장

솔직한 단점도 있습니다. Zellij는 tmux보다 메모리를 더 씁니다. SSH로 붙는 모든 서버에 깔려 있지도 않습니다. 그리고 10년 치 근육 기억과 잘 다듬은 .tmux.conf가 있다면 굳이 바꿔서 얻을 게 크지 않을 수 있습니다. Zellij 공식 문서도 이 점에 대해 느긋합니다. 명백한 업그레이드가 아니라 다른 트레이드오프일 뿐입니다.

10. 함정들

  • Ctrl q는 세션을 죽입니다. 확인 절차가 없습니다. 불안하면 shared_except "locked" 아래에 bind "Ctrl q" { SwitchToMode "Normal"; }로 다시 바인딩하세요.
  • Alt 키가 Zellij까지 안 갈 수 있습니다. 일부 터미널은 Esc 접두 시퀀스를 대신 보냅니다. macOS Terminal / iTerm2에서는 “Use Option as Meta key”를 켜세요. 아니면 직접 바인딩을 추가하면 됩니다.
  • Ctrl g는 전부 잠급니다. 갑자기 단축키가 안 먹으면 잠금 모드에 들어간 겁니다. 상태 표시줄에 그렇게 표시됩니다. Ctrl g를 다시 누르면 풀립니다.
  • Vim/Emacs 사용자 주의: Ctrl p, Ctrl n, Ctrl b, Ctrl s, Ctrl o, Ctrl t, Ctrl h가 전부 Zellij에 잡혀 있습니다. config.kdl에서 다시 바인딩하거나, 에디터를 쓰는 동안 잠금 모드(Ctrl g)를 쓰세요.
  • macOS 설정 경로는 ~/.config가 아닙니다. 그렇게 만들고 싶으면 ZELLIJ_CONFIG_DIR을 설정하세요.
  • 커스텀 레이아웃은 기본 레이아웃을 대체합니다. default_tab_template이 없으면 바도 없습니다.

다음 단계

  • 플러그인: 상태 표시줄, 탭 바, 세션 매니저, 파일 브라우저가 전부 플러그인입니다. WebAssembly로 컴파일되는 것이면 무엇이든 플러그인이 될 수 있습니다. Ctrl o 다음 p로 플러그인 매니저가 열립니다. 볼 만한 것: zjstatus(자유도 높은 상태 표시줄), zellij-forgot(검색 가능한 단축키 치트시트).
  • 테마: 수십 개가 내장되어 있고 Ctrl o 다음 c에서 실시간 미리보기가 됩니다.
  • 다중 페인 선택: Alt+왼쪽 클릭으로 페인을 표시한 뒤 한꺼번에 닫거나, 쌓거나, 탭으로 분리할 수 있습니다.
  • 레이아웃을 레포에 커밋하세요. 여기서 가장 레버리지가 큰 한 가지입니다.

참고 자료

Related Posts