Installation & Usage

To install or upgrade:

$ pip install -U ucs-detect

To use:

To run a detailed test and store a yaml report to disk:

$ ucs-detect --save-yaml=data/my-terminal.yaml --limit-codepoints=5000 --limit-words=5000 --limit-errors=500

Test Results

More than twenty modern terminals for Windows, Linux, and Mac were tested, their results have been collected into this repository and a detailed summary is published at URL https://ucs-detect.readthedocs.io/results.html

An article describing the development of ucs-detect and summarizing the results for the 1.0.4 release of ucs-detect, November 2023 is published at https://www.jeffquast.com/post/ucs-detect-test-results/

A follow-up November 2025 article discussing the results of another round of testing, including DEC Private Modes support, for release of ucs-detect 1.0.8 is published at https://www.jeffquast.com/post/state-of-terminal-emulation-2025/

Individual yaml data file reports for these terminals may also be inspected at the repository folder data, https://github.com/jquast/ucs-detect/tree/master/data

Please note that results will be shared with Terminal Emulator projects and this information may become out of date as they improve their support for Unicode. Please do not expect the maintainers of ucs-detect to update these data files. If you wish for this report to be corrected for any given Terminal, please feel free to submit a pull request with an update to the yaml data files.

Problem

Many East Asian languages contain Wide (W) or Fullwidth (F) characters, meaning that each character occupies 2 cells instead of 1. Further, many languages contain special combining characters that are “zero width”, meaning they do not occupy any cells, only modifying the previous one as a “combining” character. Finally, there are “Zero Width Joiner” and “Variation Selector-16” characters that are used in sequence for Emoji characters.

A terminal application that displays these characters may have trouble determining how it will be displayed to the end-user. This problem happens often, because the Unicode Consortium releases new versions of the Unicode Standard periodically, but the source code of libraries and applications are not updated at the same time, or at all!

Finally, a terminal emulator may have varying levels of support. For example, at time of this writing, Microsoft’s Terminal.exe supports up to Unicode 15.0 for Wide characters, is missing support for 27 characters of Unicode 13.0, has no support for Emoji ZWJ, fully supports all VS-16 sequences, but fails to correctly categorize many Zero-Width for 88 or more of the world’s languages.

Solution

The most important factor is to determine whether the Terminal Emulator complies with the Specification published by the python wcwidth library.

This program, ucs-detect, is able to automatically detect the version and feature level support of unicode that the connecting Terminal supports for WIDE, ZERO, ZWJ, and VS-16 characters.

How it works

The solution in this program is the use of the Query Cursor Position terminal sequence, which asks, “where is the cursor?”. This is a hidden sequence that a Terminal Emulator automatically responds to.

By use of this sequence, and the data tables of the wcwidth library, we can test for compliance of the python wcwidth library Specification.

The use of Query Cursor Position is inspired by the resize(1) program distributed with X11, which determines the terminal size over transports that are not capable of communicating by signal or forwarding by environment value, such as over a serial line. resize(1) simply moves to (999, 999) then asks, “where is my cursor?” and the response is understood to be the terminal size.

Updating Results

Use the re-run.py script to update the results for a new version of a terminal that is already tracked, for example:

$ python re-run.py data/contour.yaml

This will re-execute ucs-detect with the test with the same parameters as the previous test. The new results will overwrite the existing.

Or, to submit results for a new terminal not previously tracked:

$ ucs-detect --save-yaml=data/jeffs-own-terminal.yaml --limit-codepoints=5000 --limit-words=5000 --limit-errors=1000

Conditionally you may reduce the test size for slow terminals like those using libvte which require more than 5 hours to complete.

Create a pull draft pull request to this repository with your change and a github commit status should be reported by readthedocs.org, and, clicking “Details” should show the html preview.

Problem Analysis

Use the CLI argument, --stop-at-error= to interactively investigate discrepancies as they are detected. For example:

$ ucs-detect --stop-at-error 'Hindi'

This presents output when an error occurs during Hindi language testing:

ucs-detect: testing language support: Hindi
मानव

Failure in language 'Hindi':
+----------------------------+
|            मानव             |
+----------------------------+

measured by terminal: 4
measured by wcwidth:  3

printf '\xe0\xa4\xae\xe0\xa4\xbe\xe0\xa4\xa8\xe0\xa4\xb5\n'
from blessed import Terminal
term = Terminal()
y1, x1 = term.get_location(); print('मानव', end='', flush=True); y2, x2 = term.get_location()
assert x2 - x1 == 3