从 git 仓库编译需要 GCC、make、Autoconf、Automake、Libtool 和 GLib 开发包;构建命令行工具还需 FreeType2 开发包,其余图像格式库为可选依赖;一般用户建议直接用发行版或官方软件包,而非自行编译。
chafa
hpjanssonLGPL-3.0活跃维护在终端里直接显示图片的命令行工具和 C 库,支持 Sixel、Kitty、iTerm2 等协议,把图片转成 ANSI 字符或彩色图形输出。
📺🗿 Terminal graphics for the 21st century.
git clone https://github.com/hpjansson/chafa.git
./autogen.sh
make
sudo make installREADME 未说明显存或 GPU 要求;作为终端字符画工具,在普通 CPU 上运行即可。
把图片和动图转成终端里的 ANSI/Unicode 字符画,从老式电传机到现代终端模拟器都能用
在终端里直接显示图片的命令行工具和 C 库,支持 Sixel、Kitty、iTerm2 等协议,把图片转成 ANSI 字符或彩色图形输出。
核心能力
- 将图片和动画 GIF 转换为 ANSI/Unicode 字符画
- 核心功能由带公开文档 API 的 C 库提供
- 支持 FreeType2、libjpeg、libwebp、librsvg 等多种图像格式
- 提供 Python 与 JavaScript(WebAssembly)绑定
- 兼容范围广,从历史电传机到现代终端模拟器
容易踩的坑
- 1.18.3Chafa 1.18.3最新正式版2026-09-23 · 2026-09-23 16:59 UTC
This is a bugfix release.
-
libheif 1.12.0 or later is now formally required for HEIF support. We were already calling functions introduced in 1.9.0 and 1.12.0.
-
Sixels are no longer used inside tmux when the outer terminal can't display them. tmux claims the capability on its own behalf regardless of what's outside it, so we now ask what its client supports instead (#348, reported by @guerda).
-
Padding and fully transparent areas revealed by alpha thresholding are now correctly painted in the flat background color instead of the closest match (#354, reported by @ismay-tue).
-
Bug fixes: #347 Alignment-induced crash on AMD/CachyOS (reported by @yeslamm and @quantumfate). [unfiled] CLI: Hang when
--fileswas used and standard input was a pipe. [unfiled] CLI: Potential busy-wait for a complete token from a file list. [unfiled] CLI: TIFF images decoded with wrong channel order on big-endian. [unfiled] CLI: Integer overflow in image loader size arithmetic (@zouyonghe). [unfiled] CLI: Unbounded allocation decoding GIF frames larger than the file's logical extent. [unfiled] OOB read one entry past the end of the palette color table. [unfiled] Double free of the pixel canvas afterchafa_canvas_new_similar(). [unfiled] Spurious pen added to palettes with fewer than 255 colors.
-
- 1.18.2Chafa 1.18.22026-04-29 · 2026-04-29 21:52 UTC
查看更新说明
This is a bugfix release focused on security, hardening and correctness. One of the listed bugs is related to "unreasonable" CLI parameters like output sizes hundreds of thousands of cells wide; while OOB access is always a bug, users are reminded that we don't recommend forwarding CLI parameters from untrusted sources without prior sanitization.
Thanks to everyone who contributed patches and analysis.
-
Support BigTIFF images (#328, reported by @govinda-kamath).
-
Bug fixes: [unfiled] Integer overflow and OOB write with big output size (@Captainjack-kor). [unfiled] OOB write in symbol-mode Floyd-Steinberg dithering. [unfiled] CLI: Incomplete sanitization of filenames printed to terminal. [unfiled] CLI: Integer overflow in XWD header validation. [unfiled] CLI: Pointer arithmetic past end of GIF file allocation. [unfiled] OOB reading canvas cell colors in FGBG mode. [unfiled] Compiler warnings from headers with C99 and -Wpedantic.
-
- 1.18.1Chafa 1.18.12026-02-08 · 2026-02-08 17:34 UTC
查看更新说明
This is a bugfix and quality-of-life release.
-
New option:
--probe-mode=[any|ctty|stdio]. This specifies whether to probe the terminal through stdio or ctty (usually/dev/tty). Defaults toany, which will probe stdio if it looks like a tty, otherwise the ctty. This allows the terminal to be probed when I/O is redirected (#325, reported by @algometric). -
We now try harder to restore the terminal to a usable state after
SIGINTis received, even if we couldn't do a clean exit in a reasonable time frame (#309, reported by @saitoha). -
Bash completions were added and zsh completions updated (#315, @desertstsung).
-
Improved compatibility for the Kitty protocol, specifically with iTerm2 (@zouyonghe).
-
Bug fixes: #184 Test failure on sparc64 (reported by @cdluminate). #292 Test failure on i386 (reported by @cdluminate). #321 Bad console modes on win32 after exit (reported by @juliannoble). [unfiled] Stalling on closed output pipe on OpenBSD.
-
- 1.18.0Chafa 1.18.02025-11-10 · 2025-11-10 00:30 UTC
查看更新说明
This is a feature and bugfix release.
-
Increased GLib minimum version to 2.58 (released in 2018).
-
New options:
--files=FNAMEand--files0=FNAME. These allow reading lists of input files from a file or standard input. Paths can be separated by newlines or a zero byte (--files0). These options can be specified multiple times. -
New option:
--link=[auto|on|off]. When used with--label, this controls whether each label should be anOSC 8-style hyperlink to its input file. -
Multiple files can now be decoded in parallel. This greatly speeds up grid mode on multi-core systems. Controllable with
--threads. -
ConHost support was removed due to incompleteness and lack of interest.
-
Image loaders:
- Added support for CoreGraphics loaders on MacOS (#301, @saitoha).
- Added support for HEIF files on all platforms (#297).
-
Terminal support:
- Improved detection of ghostty inside tmux (#296, reported by @timsofteng).
- Added support for GNU/Hurd console.
-
Tests:
- Expanded symbol matching tests with more cases and detailed diagnostics.
- Added a test for CLI tool return values in various scenarios.
-
Bug fixes: #293 Don't leave stdin in non-blocking mode (found by @YanceyChiew). [unfiled] Use glibtoolize when libtoolize is unavailable (@saitoha). [unfiled] GNU/Hurd: Don't stall if pipe is closed on remote end. [unfiled] _mm_empty() not always called immediately after MMX use. [unfiled] FP division by zero possible in sixel palette generation. [unfiled] Don't wait for response if probing is unsupported. [unfiled] Wrong exit code returned on some failures.
-
- 1.16.2Chafa 1.16.22025-07-04 · 2025-07-04 22:08 UTC
查看更新说明
This is a bugfix release. It also improves I/O robustness and SVG rendering quality.
- Bug fixes:
#288 SVG scaling seems to be done after bitmap conversion (found by @joveian).
[unfiled] MinGW: Undeclared function error for
strlen()(@carlo-bramini). [unfiled] Assert when usingchafa_canvas_draw_all_pixels()with Kitty passthrough (found by @ravachol). [unfiled] Hangs when running with closed stdin (found by @SapphirusBeryl). [unfiled] Potential overrun when output dimension is exactly 1 pixel. [unfiled] Small memory leak on failed load in the grid layout. [unfiled] Occasional warnings from JPEG loader that should not be printed.
- Bug fixes:
#288 SVG scaling seems to be done after bitmap conversion (found by @joveian).
[unfiled] MinGW: Undeclared function error for
用户点评
登录用户的真实使用记录,可按版本和硬件筛选还没有人点评。第一个说出真实体验的人最有价值。
About
Chafa is a command-line utility that converts image data, including animated GIFs, into graphics formats or ANSI/Unicode character art suitable for display in a terminal. It has broad feature support, allowing it to be used on devices ranging from historical teleprinters to modern terminal emulators and everything in between.
The core functionality is provided by a C library with a public, well-documented API.
Both library and frontend tools are covered by the Lesser GPL license, version 3 or later (LGPLv3+).
The official web pages and C API documentation can be found online. Check out the gallery for screenshots.
Installing
Chafa is most likely packaged for your distribution, so if you're not going to hack on it, you're better off using official packages. If you want to build the latest and greatest yourself, read on.
You will need GCC, make, Autoconf, Automake, Libtool and the GLib
development package installed to compile Chafa from its git repository. If
you want to build the command-line tool chafa and not just the library,
you will additionally need development packages for:
- FreeType2. Often packaged as
libfreetype6-devorfreetype2-devel. - libavif (optional). Look for
libavif-devorlibavif-devel. - libdeflate (optional, speeds up PNG decoding). Look for
libdeflate-devorlibdeflate-devel. - libheif 1.12 or later (optional). Look for
libheif-devorlibheif-devel. - libjpeg (optional). Look for
libjpeg-dev,libjpeg62-develorlibjpeg8-devel. - libjxl (optional). Look for
libjxl-devorlibjxl-devel. - librsvg (optional). Look for
librsvg2-devorlibrsvg-devel. - libtiff (optional). Look for
libtiff5-devorlibtiff-devel. - libwebp (optional). Look for
libwebp-devorlibwebp-devel.
If you want to build documentation, you will also need gtk-doc.
Start by cloning the repository:
$ git clone https://github.com/hpjansson/chafa.git
Then cd to the toplevel directory and issue the following shell commands:
$ ./autogen.sh
$ make
$ sudo make install
That should do it!
Python bindings
Erica Ferrua Edwardsdóttir maintains excellent Python bindings for Chafa. If Python's your thing, check them out. They are easy to use and come with a detailed tutorial.
JavaScript bindings
Héctor Molinero Fernández maintains wonderful JavaScript bindings built around his WebAssembly port. These are available from NPM and can be used in Node.js, web browsers, and more.