winds.from.oz 技術メモ

Yazi の導入と Sixel 画像プレビュー

Posted:

目的

Yazi を terminal file manager として使い、画像 preview は Sixel 経由に寄せる。

対象環境は、ローカル desktop の WezTerm + tmux。 2026-05-29 に確認した環境では、Yazi と tmux は次の状態だった。

Yazi 26.5.6 (aa52643 2026-05-05)
tmux next-3.7
WezTerm 20240203-110809-5046fc22
tmux build flags: enable-sixel=Supported

導入確認

yazi と ya は /usr/local/bin に入っている。

command -v yazi
command -v ya
yazi --version
ya --version

依存関係の確認には yazi --debug を使う。

yazi --debug

fish から使う

fish では ~/.config/fish/my_functions/yazi.fish に wrapper を置く。

y function は、Yazi 終了時に選択中の directory へ cd するためのもの。 yazi function は、Yazi を直接起動した場合にも同じ Sixel shim を通すためのもの。

function __yazi_should_force_sixel
 if set -q ZELLIJ_SESSION_NAME
  return 0
 end

 if set -q TMUX
  command tmux display -p '#{sixel_support}' 2>/dev/null | string match -q 1
  return $status
 end

 test "$TERM_PROGRAM" = WezTerm
end

function __yazi_sixel
 if __yazi_should_force_sixel
  set -l zellij_name yazi-sixel
  if set -q ZELLIJ_SESSION_NAME
   set zellij_name $ZELLIJ_SESSION_NAME
  end

  set -lx ZELLIJ_SESSION_NAME $zellij_name
  command yazi $argv
 else
  command yazi $argv
 end
end

function yazi
 __yazi_sixel $argv
end

function y
 set tmp (mktemp -t "yazi-cwd.XXXXXX")
 __yazi_sixel $argv --cwd-file="$tmp"
 if read -z cwd < "$tmp"; and [ -n "$cwd" ]; and [ "$cwd" != "$PWD" ]
  builtin cd -- "$cwd"
 end
 rm -f -- "$tmp"
end

構文確認。

fish -n ~/.config/fish/my_functions/yazi.fish

Sixel に寄せる理由

Yazi の画像 preview は、terminal emulator と multiplexer の検出結果から adapter が決まる。

WezTerm は Yazi 26.5.6 では Iip, Sixel の順で adapter 候補になる。 つまり、WezTerm として自然に検出されると Inline Images Protocol 側が先に選ばれやすい。

一方、Yazi 26.5.6 の実装では ZELLIJ_SESSION_NAME がある場合、adapter 候補を Sixel のみに絞る。 このため、実際に Zellij を使うわけではなく、Yazi process にだけ ZELLIJ_SESSION_NAME=yazi-sixel を渡して Sixel を選ばせる。

この shim は Yazi の現行実装に依存する。 将来 Yazi に adapter を直接指定する公開設定が入った場合は、そちらに置き換える方が素直。

tmux 設定

tmux 側では、Sixel と passthrough が必要。

~/.config/tmux/main.conf:

set-option -g allow-passthrough on

# Yazi の画像プレビュー用。tmux 越しに外側 terminal の情報と Sixel を認識させる。
set-option -ga update-environment TERM
set-option -ga update-environment TERM_PROGRAM
set-option -ga update-environment TERM_PROGRAM_VERSION
set-option -as terminal-features ',xterm*:sixel'

既存 tmux server へ即時反映する場合。

tmux set-option -ga update-environment TERM \; \
  set-option -ga update-environment TERM_PROGRAM \; \
  set-option -ga update-environment TERM_PROGRAM_VERSION \; \
  set-option -as terminal-features ',xterm*:sixel'

通常は tmux server を再起動した方が環境変数の反映が分かりやすい。

tmux kill-server
tmux

確認

tmux 側。

tmux display -p '#{sixel_support} #{client_termname} #{client_termtype} #{client_termfeatures}'
tmux show -gq allow-passthrough
tmux show -gq update-environment

期待例。

1 xterm-256color WezTerm 20240203-110809-5046fc22 bpaste,ccolour,clipboard,cstyle,focus,RGB,sixel,title
allow-passthrough on

Yazi 側。

yazi --debug

期待値。

Emulator.detect     : Emulator { kind: Left(WezTerm), version: "WezTerm 20240203-110809-5046fc22", ... }
Adapter.matches    : Sixel
Dimension.available: Dimension { rows: 48, columns: 192, width: 3072, height: 1536 }
TMUX               : true
tmux build flags   : enable-sixel=Supported
ZELLIJ_SESSION_NAME: Some("yazi-sixel")

Zellij version: No such file or directory は、この shim では問題ではない。 Zellij を実行しているわけではなく、Yazi の adapter 選択だけを Sixel に寄せている。

不定点

  • ZELLIJ_SESSION_NAME を使うのは Yazi 26.5.6 の実装に依存した shim。
  • yazi --debug が Adapter.matches: Sixel になっても、実際の描画確認は GUI terminal 上で画像ファイルへ cursor を合わせて見る必要がある。
  • remote SSH、nested tmux、Neovim terminal 内では検出結果が変わる可能性がある。
  • WezTerm 側は Sixel 以外に iTerm2 inline image protocol も扱えるため、Yazi の adapter 優先順位が変わると挙動が変わる可能性がある。

参考