---
id: wcwidth
version: "0.8.2"
license: MIT
license_treatment: permissive
maintenance: active
---

# wcwidth — Measures the displayed width of unicode strings in a terminal

License: permissive · Maintenance: active · Popularity: top 1,000 on PyPI

## Install

pip install wcwidth
uv add wcwidth
poetry add wcwidth

## Description

|pypi_downloads| |codecov| |license|

============
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

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

    >>> # result consumes 5 total cells, 6 expected,
    >>> '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...

## AI interpretation — verify before relying

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.

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.

[View on SkillFed](https://skillfed.io/packages/wcwidth) · [View on PyPI](https://pypi.org/project/wcwidth/)