wcwidth

Measures the displayed width of unicode strings in a terminal

wcwidth Permissive license MIT Active ★ 463 v0.8.2 released 2026-06-29

Install

wcwidth on PyPI

pip

pip install wcwidth

uv

uv add wcwidth

poetry

poetry add wcwidth

Package facts

License	MIT (permissive)
Python support	supports the current Python release (>=3.8)
Install friction	low — pure-Python wheel
Runtime dependencies	none
Maintenance	actively maintained — 45 days since the last release
Last repo commit	2026-08-07
First released	2014-05-05
Popularity	one of the top 1,000 most-downloaded packages on PyPI (30-day window, as of 2026-08-13)
Known vulnerabilities	none known (OSV.dev, checked 2026-08-13)

Evidence: wcwidth-0.8.2-py3-none-any.whl

Keywords: cjk, combining, console, eastasian, emoji, emulator, terminal, unicode, wcswidth, wcwidth, xterm

Development Status :: 5 - Production/StableEnvironment :: ConsoleIntended Audience :: DevelopersNatural Language :: EnglishOperating System :: POSIXProgramming Language :: Python :: 3 :: OnlyProgramming Language :: Python :: 3.10Programming Language :: Python :: 3.11Programming Language :: Python :: 3.12Programming Language :: Python :: 3.13Programming Language :: Python :: 3.14Programming Language :: Python :: 3.15Programming Language :: Python :: 3.8Programming Language :: Python :: 3.9Topic :: Software Development :: InternationalizationTopic :: Software Development :: LibrariesTopic :: Software Development :: LocalizationTopic :: TerminalsTyping :: Typed

About wcwidth

from the package's own PyPI description — quoted content, verbatim

============ Introduction ============

This library is mainly for CLI/TUI programs that carefully produce output for Terminals.

Installation

The stable version of this package is maintained on pypi, install or upgrade, using pip::

pip install --upgrade wcwidth

Problem

All Python string-formatting functions, textwrap.wrap(), str.ljust(), str.rjust(), and str.center() incorrectly measure the displayed width of a string as equal to the number of their codepoints.

Some examples of incorrect results:

.. code-block:: python

&gt;&gt;&gt; # result consumes 16 total cells, 11 expected,
&gt;&gt;&gt; 'コンニチハ'.rjust(11, 'X')
'XXXXXXコンニチハ'

&gt;&gt;&gt; # result consumes 5 total cells, 6 expected,
&gt;&gt;&gt; 'café'.center(6, 'X')
'caféX'

Solution

The lowest-level functions in this library are derived from POSIX.1-2001 and POSIX.1-2008 wcwidth(3) and wcswidth(3), which this library precisely copies by interface as wcwidth() and wcswidth(). These functions return -1 when C0 and C1 control codes are present.

An easy-to-use width() function is provided as a wrapper of wcswidth() that...

Read as markdown · JSON record · Source repository · Homepage

AI interpretation — verify before relying

AI-generated interpretation of the package facts above; every digit, version, license, or vulnerability id it cites is grounded in the facts already shown on this page

Measures the displayed width of Unicode strings in terminals, accounting for wide characters, combining marks, and terminal escape sequences—fixing the incorrect width calculations of Python's standard string formatting functions.

Installs cleanly with no runtime dependencies and a pure-Python wheel. Actively maintained with a release 45 days ago and consistent commit activity.

MIT license permits unrestricted use, modification, and distribution in both open-source and proprietary projects.

Usage

pip install wcwidth

import wcwidth

# Measure width of a single codepoint
print(wcwidth.wcwidth('\u2640'))  # Returns 1

# Measure width of a string
print(wcwidth.wcswidth('\u2640\ufe0f'))  # Returns 2

# Measure with terminal control sequences
print(wcwidth.width('\x1b[38;2;255;150;100mWARN\x1b[0m'))  # Returns 4

Verdict: A stable, zero-dependency library ideal for CLI/TUI applications that need accurate terminal width measurement. Active maintenance, MIT license, and no known vulnerabilities make it a reliable choice for handling Unicode display width across Python 3.8–3.15.

Needs verification

Degree of compliance with terminal emulators beyond those listed (Windows Terminal, WezTerm, ghostty, contour, foot)
Performance characteristics when processing very large strings or high-frequency width calculations

unicode string width terminalwcwidth wcswidth measurementterminal display width calculationcjk emoji character widthansi escape sequence widthterminal text justificationgrapheme cluster width