Syxel
Early alpha release. Interfaces and output may still change, and some rough edges remain. Bug reports (and any other feedback) are very welcome: please open an issue at github.com/luispedro/syxel/issues.
SIXEL in Python: display images directly in your terminal.
syxel is a small, pure-Python package that converts images to the
SIXEL escape-sequence protocol and writes
them to standard output. If your terminal speaks SIXEL, the image appears inline,
no image viewer required.
It ships a command line tool, imcat, and a matplotlib backend, so that
plt.show() draws your plots in the terminal.
Installation
pip install syxel
Or, from a checkout, for development (the imcat script then tracks your
working copy):
pip install -e .
Requires Python 3.11 or later.
The base install only depends on numpy, which is enough to convert arrays (or matplotlib figures) to SIXEL. Reading image files and the matplotlib backend each come as an extra:
pip install 'syxel[imcat]' # the imcat command line tool
pip install 'syxel[matplotlib]' # the matplotlib backend
pip install 'syxel[imcat,matplotlib]'
Dependencies
- numpy
- imread — optional (
imcatextra), image loading for the command line tool - matplotlib — optional (
matplotlibextra), only for the backend
Usage
imcat image.png
Several images can be given at once; each is written followed by a newline, so they stack vertically:
imcat one.png two.jpg three.tiff
Images larger than 800x1200 are subsampled (halved repeatedly) until they fit. Override the limits with:
imcat --max-height 400 --max-width 600 image.png
How many colours the image is quantized to is the terminal's business: SIXEL
draws from a palette of colour registers, and terminals differ in how many they
provide (16 on the original DEC VT340, 256 by default today, up to 1024 for
xterm configured with numColorRegisters). imcat asks the terminal with
XTSMGRAPHICS and uses whatever it says, falling back to 255 for terminals that do
not answer. Set it by hand with --max-colours N, or for both imcat and the
matplotlib backend with the SYXEL_MAX_COLOURS environment variable:
imcat --max-colours 1024 image.png # or
SYXEL_MAX_COLOURS=1024 imcat image.png
To see what the terminal has to say for itself, ask for a report instead of an image:
$ imcat --info
syxel version: 0.2
Terminal: foot
SIXEL support: yes
Colour registers: 1024
Terminal size: 120x40 characters, 1440x960 pixels
Largest image: 1000x1000 pixels
Colours in use: 1024 (from the terminal)
Images fit into: 1200x800 pixels (--max-width/--max-height)
Everything above the last two lines is what the terminal answered (unknown
where it said nothing at all, which is what a terminal without SIXEL support
usually does); the last two are what imcat would do with an image, so
--info can be combined with --max-colours and the size limits to see their
effect.
Full option list:
| Option | Meaning |
|---|---|
--max-height N |
subsample until the image is at most N pixels high (default: 800) |
--max-width N |
subsample until the image is at most N pixels wide (default: 1200) |
--max-colours N |
quantize to at most N colours (default: ask the terminal) |
--info |
report what the terminal supports and exit |
--version |
print the version and exit |
--help |
print usage and exit |
Terminal support
You need a terminal emulator with SIXEL support, such as
foot,
WezTerm,
mlterm, or
xterm started with SIXEL enabled (xterm -ti vt340). In a terminal without
SIXEL support you will just see a wall of escape-sequence bytes; imcat --info
asks the terminal whether it can draw them before you try.
Since imcat writes to sys.stdout.buffer, you can also capture the raw byte
stream instead of rendering it:
imcat image.png > image.six
matplotlib backend
syxel.backend_sixel is a matplotlib backend that draws figures into the terminal
instead of opening a window. Select it from the environment:
MPLBACKEND=module://syxel.backend_sixel python plot.py
or from Python, before importing pyplot:
import matplotlib
matplotlib.use('module://syxel.backend_sixel')
import matplotlib.pyplot as plt
plt.plot([1, 4, 9])
plt.show() # the figure appears in the terminal
With matplotlib 3.9 or later the short name matplotlib.use('sixel') also works,
via an entry point.
The figure is scaled to fill the terminal: its dpi is raised or lowered so that it
fits the window, which redraws it at the right resolution rather than resampling
it. Terminals that do not report their size in pixels (some multiplexers) fall
back to 1200x800; set SYXEL_MAX_WIDTH and SYXEL_MAX_HEIGHT to override.
The palette comes from the terminal in the same way as for imcat, including for
savefig (a figure has nothing to say about how many colour registers there are);
SYXEL_MAX_COLOURS overrides it.
savefig gains a sixel format, which writes at the figure's own size:
fig.savefig('plot.sixel') # or
fig.savefig(sys.stdout.buffer, format='sixel')
Each plt.show() prints the figures drawn so far and then drops them, so a script
with several show() calls does not reprint earlier figures.
Using it as a library
The conversion is available directly, independently of the command line tool:
import sys
from syxel.imcat import load_image
from syxel.sixel import rgb_to_palette, write_sixel
rgb = load_image('image.png') # (M,N,3) uint8 array
active, data = rgb_to_palette(rgb) # palette (P,3) and indexed image (M,N)
write_sixel(sys.stdout.buffer, data, active)
write_sixel accepts any object with a write method taking bytes, so an
io.BytesIO works for testing or for building the sequence in memory.
The same is true of figures, without going through the backend machinery:
from syxel.backend_sixel import write_figure
write_figure(sys.stdout.buffer, fig)
How it works
The pipeline has three stages:
-
Load (
load_image) — read the file withimread, subsample by[::2,::2]until it fits the size limits, expand greyscale to three channels and drop any alpha channel. The result is an (M,N,3) uint8 array. -
Quantize (
rgb_to_palette) — the terminal has a limited number of colour registers (syxel.terminal.colour_registersasks it how many), so colours are counted and the most frequent ones that fit are kept. If those do not cover at least half of the image, the colours are rounded — one low bit at a time, from blue first, then red, then green, then the next bit of each — until the most frequent of what is left do cover half of it, so the registers end up where the image actually has colours. Every distinct source colour is then mapped to its nearest palette entry by squared Euclidean distance. -
Emit (
write_sixel) — write the escape sequences. The image is processed in bands of six rows, with one pass per colour present in the band; each output byte encodes one column's six-pixel bitmask. A final band shorter than six rows only sets the bits of the rows that exist.
The matplotlib backend replaces the first stage: it renders the figure through Agg and hands the resulting pixels to the same last two stages.
Development
Tests use pytest and hypothesis, and are run through pixi:
pixi run -e test test
CI runs the suite on Python 3.11 through 3.14.
Releases are cut by pushing a v<version> tag matching syxel/syxel_version.py
(for example git tag v0.1 && git push origin v0.1), which builds the sdist and
wheel and uploads them to PyPI through
trusted publishing.
License
MIT (see COPYING.MIT).
Copyright (c) 2024–2026 Luis Pedro Coelho
Metadata
Release files for syxel 0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| syxel-0.2.tar.gz | 35.9 kB | Without provenance | Details for syxel-0.2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| syxel-0.2-py3-none-any.whl | Python 3 | none | any | Details for syxel-0.2-py3-none-any.whl |
Total release size: 57.1 kB
Release files / syxel-0.2.tar.gz
| Download URL | syxel-0.2.tar.gz |
|---|---|
| Size | 35.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a1874320575b9606949724f0d918b3eafcfc83bf6af052b865b058dee50d175b
|
|
BLAKE2b-256 checksum How to use checksums |
685b8d673eef5489363b8815ea47541d070f18933f5559dafc8519a6cda57af8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.11.9
|
Release files / syxel-0.2-py3-none-any.whl
| Download URL | syxel-0.2-py3-none-any.whl |
|---|---|
| Size | 21.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5f4c53e6a9427179b62428ee70202aeb1c6890f683ec2a328a936e658e414ced
|
|
BLAKE2b-256 checksum How to use checksums |
27102f1c02cf64989a68935629d06caf90b15243616af58179121059ce32d7db
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/5.1.0 CPython/3.11.9
|
Security for syxel 0.2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.