Skip to main content

Downloads codecov.io Code Coverage MIT License

Introduction

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.

Installation

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

pip install wcwidth

Example

Problem: given the following phrase (Japanese),

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

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

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

>>> 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('コンニチハ'))
10

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

-1

Indeterminate (not printable).

0

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

2

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

1

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 https://wcwidth.readthedocs.io

Developing

Install wcwidth in editable mode:

pip install -e .

Execute unit tests using tox for all supported Python versions:

tox -e py36,py37,py38,py39,py310,py311,py312,py313,py314

Updating Unicode Version

Regenerate python code tables from latest Unicode Specification data files:

tox -e update

The script is located at bin/update-tables.py, requires Python 3.9 or later. It is recommended but not necessary to run this script with the newest Python, because the newest Python has the latest unicodedata for generating comments.

Building Documentation

This project is using sphinx 4.5 to build documentation:

tox -e sphinx

The output will be in docs/_build/html/.

Updating Requirements

This project is using pip-tools to manage requirements.

To upgrade requirements for updating unicode version, run:

tox -e update_requirements_update

To upgrade requirements for testing, run:

tox -e update_requirements37,update_requirements39

To upgrade requirements for building documentation, run:

tox -e update_requirements_docs

Utilities

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 -r requirements-develop.txt from this projects main folder. For example, an interactive browser for testing:

python ./bin/wcwidth-browser.py

Uses

This library is used in:

Other Languages

History

0.2.14 2025-09-22
  • Drop Support for Python 2.7 and 3.5. PR #117.

  • Update tables to include Unicode Specifications 16.0.0 and 17.0.0. PR #146.

  • Bugfix U+00AD SOFT HYPHEN should measure as 1, versions 0.2.9 through 0.2.13 measured as 0. PR #149.

0.2.13 2024-01-06
  • Bugfix zero-width support for Hangul Jamo (Korean)

0.2.12 2023-11-21
  • re-release to remove .pyi file misplaced in wheel files Issue #101.

0.2.11 2023-11-20
  • Include tests files in the source distribution (PR #98, PR #100).

0.2.10 2023-11-13
  • Bugfix accounting of some kinds of emoji sequences using U+FE0F Variation Selector 16 (PR #97).

  • Updated Specification.

0.2.9 2023-10-30
  • Bugfix zero-width characters used in Emoji ZWJ sequences, Balinese, Jamo, Devanagari, Tamil, Kannada and others (PR #91).

  • Updated to include Specification of character measurements.

0.2.8 2023-09-30
  • Include requirements files in the source distribution (PR #82).

0.2.7 2023-09-28
  • Updated tables to include Unicode Specification 15.1.0.

  • Include bin, docs, and tox.ini in the source distribution

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/update-tables.py 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 readthedocs.io.

  • 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 https://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c:

* 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.

Metadata

Release files for wcwidth 0.2.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wcwidth 0.2.14
File Size Uploaded Provenance Actions
wcwidth-0.2.14.tar.gz 102.3 kB Without provenance Details for wcwidth-0.2.14.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wcwidth 0.2.14
File Interpreter ABI Platform Actions
wcwidth-0.2.14-py2.py3-none-any.whl Python 3, Python 2 none any Details for wcwidth-0.2.14-py2.py3-none-any.whl

Total release size: 139.6 kB

Release files / wcwidth-0.2.14.tar.gz

Download URL wcwidth-0.2.14.tar.gz
Size 102.3 kB
Tags Source
SHA-256 checksum
How to use checksums
4d478375d31bc5395a3c55c40ccdf3354688364cd61c4f6adacaa9215d0b3605
BLAKE2b-256 checksum
How to use checksums
24306b0809f4510673dc723187aeaf24c7f5459922d01e2f794277a3dfb90345
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.6

Release files / wcwidth-0.2.14-py2.py3-none-any.whl

Download URL wcwidth-0.2.14-py2.py3-none-any.whl
Size 37.3 kB
Tags Python 2 Python 3
SHA-256 checksum
How to use checksums
a7bb560c8aee30f9957e5f9895805edd20602f2d7f720186dfd906e82b4982e1
BLAKE2b-256 checksum
How to use checksums
afb5123f13c975e9f27ab9c0770f514345bd406d0e8d3b7a0723af9d43f710af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.6

Security for wcwidth 0.2.14

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.14 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