Skip to main content

Measures the displayed width of unicode strings in a terminal

Project description

Downloads Code Coverage MIT License


This library is mainly for CLI programs that carefully produce output for Terminals, or make pretend to be an emulator.

Problem Statement: The printable length of most strings are equal to the number of cells they occupy on the screen 1 character : 1 cell. However, there are categories of characters that occupy 2 cells (full-wide), and others that occupy 0 cells (zero-width).

Solution: POSIX.1-2001 and POSIX.1-2008 conforming systems provide wcwidth(3) and wcswidth(3) C functions of which this python module’s functions precisely copy. These functions return the number of cells a unicode string is expected to occupy.


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

pip install wcwidth


Problem: given the following phrase (Japanese),

>>>  text = u'コンニチハ'

Python incorrectly uses the string length of 5 codepoints rather than the printible length of 10 cells, so that when using the rjust function, the output length is wrong:

>>> print(len('コンニチハ'))

>>> print('コンニチハ'.rjust(20, '_'))

By defining our own “rjust” function that uses wcwidth, we can correct this:

>>> def wc_rjust(text, length, padding=' '):
...    from wcwidth import wcswidth
...    return padding * max(0, (length - wcswidth(text))) + text

Our Solution uses wcswidth to determine the string length correctly:

>>> from wcwidth import wcswidth
>>> print(wcswidth('コンニチハ'))

>>> print(wc_rjust('コンニチハ', 20, '_'))

Choosing a Version

Export an environment variable, UNICODE_VERSION. This should be done by terminal emulators or those developers experimenting with authoring one of their own, from shell:

$ export UNICODE_VERSION=13.0

If unspecified, the latest version is used. If your Terminal Emulator does not export this variable, you can use the jquast/ucs-detect utility to automatically detect and export it to your shell.

wcwidth, wcswidth

Use function wcwidth() to determine the length of a single unicode character, and wcswidth() to determine the length of many, a string of unicode characters.

Briefly, return values of function wcwidth() are:


Indeterminate (not printable).


Does not advance the cursor, such as NULL or Combining.


Characters of category East Asian Wide (W) or East Asian Full-width (F) which are displayed using two terminal cells.


All others.

Function wcswidth() simply returns the sum of all values for each character along a string, or -1 when it occurs anywhere along a string.

Full API Documentation at


Install wcwidth in editable mode:

pip install -e.

Execute unit tests using tox:


Regenerate python code tables from latest Unicode Specification data files:

tox -e update

Supplementary tools for browsing and testing terminals for wide unicode characters are found in the bin/ of this project’s source code. Just ensure to first pip install -erequirements-develop.txt from this projects main folder. For example, an interactive browser for testing:

python ./bin/


This library is used in:

Other Languages


0.2.6 2023-01-14
  • Updated tables to include Unicode Specification 14.0.0 and 15.0.0.

  • Changed developer tools to use pip-compile, and to use jinja2 templates for code generation in bin/ to prepare for possible compiler optimization release.

0.2.1 .. 0.2.5 2020-06-23
  • Repository changes to update tests and packaging issues, and begin tagging repository with matching release versions.

0.2.0 2020-06-01
  • Enhancement: Unicode version may be selected by exporting the Environment variable UNICODE_VERSION, such as 13.0, or 6.3.0. See the jquast/ucs-detect CLI utility for automatic detection.

  • Enhancement: API Documentation is published to

  • Updated tables for all Unicode Specifications with files published in a programmatically consumable format, versions 4.1.0 through 13.0

0.1.9 2020-03-22
  • Performance optimization by Avram Lubkin, PR #35.

  • Updated tables to Unicode Specification 13.0.0.

0.1.8 2020-01-01
  • Updated tables to Unicode Specification 12.0.0. (PR #30).

0.1.7 2016-07-01
  • Updated tables to Unicode Specification 9.0.0. (PR #18).

0.1.6 2016-01-08 Production/Stable
  • LICENSE file now included with distribution.

0.1.5 2015-09-13 Alpha
  • Bugfix: Resolution of “combining character width” issue, most especially those that previously returned -1 now often (correctly) return 0. resolved by Philip Craig via PR #11.

  • Deprecated: The module path wcwidth.table_comb is no longer available, it has been superseded by module path wcwidth.table_zero.

0.1.4 2014-11-20 Pre-Alpha
0.1.3 2014-10-29 Pre-Alpha
0.1.2 2014-10-28 Pre-Alpha
0.1.1 2014-05-14 Pre-Alpha
  • Initial release to pypi, Based on Unicode Specification 6.3.0

This code was originally derived directly from C code of the same name, whose latest version is available at

* Markus Kuhn -- 2007-05-26 (Unicode 5.0)
* Permission to use, copy, modify, and distribute this software
* for any purpose and without fee is hereby granted. The author
* disclaims all warranties with regard to this software.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

wcwidth-0.2.6.tar.gz (35.5 kB view hashes)

Uploaded source

Built Distribution

wcwidth-0.2.6-py2.py3-none-any.whl (30.0 kB view hashes)

Uploaded py2 py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page