Skip to main content

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.

Downloads Test Status License: MIT

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 (imcat extra), image loading for the command line tool
  • matplotlib — optional (matplotlib extra), 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:

  1. Load (load_image) — read the file with imread, 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.

  2. Quantize (rgb_to_palette) — the terminal has a limited number of colour registers (syxel.terminal.colour_registers asks 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.

  3. 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)

Source distribution for syxel 0.2
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)

Table of built distributions (wheels) for syxel 0.2
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.2 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page