Registry / serialization / wcwidth

wcwidth

JSON →
library0.8.2pypypi✓ verified 29d ago

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
INSTALL
IMPORT
SIG · WCWIDTH
W
wcwidth
serializationpythonv0.8.2
Install
1.9s avg
Import
63ms
Disk
20MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v0.8.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.066s · 24.8MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 1.9s · import 0.060s · 25MB
20MB installed
● package 20MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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

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}')
Debug
Known issues
breakingVersion 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.
affects: 0.5.0
deprecatedThe '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.
affects: 0.5.0, 0.6.0
gotchaThe 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.
affects: All versions
breakingThe 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.
affects: All versions
gotchaThe `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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'wcwidth'
The 'wcwidth' library has not been installed in your current Python environment.
fix
pip install wcwidth
NameError: name 'wcwidth' is not defined
The 'wcwidth' function or module was called without being imported first.
fix
from wcwidth import wcwidth
TypeError: expected a character, got 'some_string'
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.
TypeError: expected a character, got <class 'int'>
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.
wcwidth returns -1
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()`.
Upgrade
Version history
0.8.2latest on PyPI · released Jun 29, 2026
Audit
Dependencies

No dependency data recorded yet.

Agent activity
19 hits · last 30 days
node
16
OpenAI (training)
1
Resources
wcwidth — pip install wcwidth · libregistry