wcwidth: Unicode String Width Measurement

0.6.0 verified Tue May 12 auth: no python install: verified quickstart: stale

wcwidth is a Python library that measures the displayed width of Unicode strings in a terminal, ensuring accurate text formatting. The current version is 0.6.0, released on January 22, 2022. The library is actively maintained with a release cadence of approximately every few months.

pip install wcwidth

Common errors

error ModuleNotFoundError: No module named 'wcwidth' ↓

cause The 'wcwidth' library has not been installed in your current Python environment.

fix

pip install wcwidth

error NameError: name 'wcwidth' is not defined ↓

cause The 'wcwidth' function or module was called without being imported first.

fix

from wcwidth import wcwidth

error TypeError: expected a character, got 'some_string' ↓

cause The 'wcwidth.wcwidth' function expects a single Unicode character string as input, but it received a string containing multiple characters.

fix

Pass only a single character to wcwidth.wcwidth(), or use wcwidth.wcswidth() for an entire string.

error TypeError: expected a character, got <class 'int'> ↓

cause The 'wcwidth.wcwidth' function expects a single Unicode character string as input, but it received a non-string type like an integer.

fix

Ensure the input to wcwidth.wcwidth() is always a single Unicode character string.

error wcwidth returns -1 ↓

cause The 'wcwidth.wcwidth' function returns -1 for control characters, non-spacing marks, or characters that do not have a defined display width in a terminal.

fix

Handle the -1 return value by filtering out or replacing such characters, or understand that it signifies a character with no display width; for full string width, use wcwidth.wcswidth().

Warnings

breaking Version 0.5.0 dropped support for many historical versions of wide and zero Unicode tables, now only the latest Unicode version (17.0.0) is supported. The 'unicode_version' keyword in wcwidth() functions is ignored, and list_versions() returns a tuple with only the latest Unicode version. ↓

fix Update your code to be compatible with Unicode version 17.0.0 and remove any reliance on the 'unicode_version' keyword.

deprecated The 'unicode_version' keyword in wcwidth() functions was deprecated in version 0.5.0 and is ignored in version 0.6.0. ↓

fix Remove the 'unicode_version' keyword from your wcwidth() function calls.

gotcha The wcwidth function may not handle all Unicode characters correctly, especially those with ambiguous widths. It's important to test with a variety of characters to ensure accurate results. ↓

fix Regularly test your application with diverse Unicode characters to identify and handle any width measurement issues.

breaking The wcwidth() function expects a single Unicode character as input. Passing a multi-character string will result in a TypeError. ↓

fix Ensure that wcwidth() is called with a single character. If you need to calculate the width of an entire string, iterate over its characters and sum their individual widths or use a helper function designed for strings.

gotcha The `wcwidth()` function expects its input `text` to be either a single string (e.g., 'abc') or an iterable where each element is a single character (e.g., `['a', 'b', 'c']`). Providing an iterable that contains multi-character strings (e.g., `['single', 'multiple_chars']`) will lead to a `TypeError: ord() expected a character, but string of length X found` when `wcwidth()` attempts to process a non-single-character element. ↓

fix Ensure that the argument passed to `wcwidth()` is either a single string or an iterable of individual characters. If you need to calculate the width of multiple strings, concatenate them into a single string or call `wcwidth()` for each string individually and sum the results.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.04s 18.3M

3.10 slim (glibc) - - 0.03s 19M

3.11 alpine (musl) - - 0.08s 20.1M

3.11 slim (glibc) - - 0.06s 21M

3.12 alpine (musl) - - 0.06s 12.0M

3.12 slim (glibc) - - 0.06s 13M

3.13 alpine (musl) - - 0.06s 11.6M

3.13 slim (glibc) - - 0.06s 12M

3.9 alpine (musl) - - 0.04s 17.8M

3.9 slim (glibc) - - 0.04s 18M

Imports

wcwidth
```
from wcwidth import wcwidth
```
Ensure correct import path to access the wcwidth function

Quickstart stale last tested: 2026-04-23

This example demonstrates how to import the wcwidth function and use it to measure the width of a Unicode string.

from wcwidth import wcwidth

# Measure the width of a Unicode string
text = 'Hello, 世界'
width = wcwidth(text)
print(f'The width of the text is: {width}')