Install & Compatibility
Where this runs
tested against v0.1.11 · 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
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 18MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.7s · import 0.000s · 19MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
wcwidth
✓ from cwcwidth import wcwidth
Imports the function to calculate the width of a single Unicode character.
wcswidth
✓ from cwcwidth import wcswidth
Imports the function to calculate the width of a Unicode string.
This quickstart demonstrates how to use `wcwidth` for single Unicode characters and `wcswidth` for entire strings or substrings, calculating their display width on a terminal. It also shows the behavior with non-printable control characters.
from cwcwidth import wcwidth, wcswidth
# Calculate width of a single character
char_width_a = wcwidth('a')
char_width_kanji = wcwidth('語')
# Calculate width of a string
string_width_hello = wcswidth('Hello')
string_width_japanese = wcswidth('コンニチハ, セカイ!')
# Calculate width of a substring (first 5 characters)
string_width_partial = wcswidth('コンニチハ, セカイ!', 5)
print(f"Width of 'a': {char_width_a}")
print(f"Width of '語': {char_width_kanji}")
print(f"Width of 'Hello': {string_width_hello}")
print(f"Width of 'コンニチハ, セカイ!': {string_width_japanese}")
print(f"Width of first 5 chars of 'コンニチハ, セカイ!': {string_width_partial}")
# Example with a non-printable character (returns -1)
non_printable_width = wcwidth('\x01') # Start of Heading control character
print(f"Width of non-printable char '\x01': {non_printable_width}")
Debug
Known issues
breakingcwcwidth frequently drops support for older Python versions with new releases. For example, version 0.1.12 dropped Python 3.10 support, 0.1.11 dropped 3.9, and 0.1.10 dropped 3.8. Ensure your Python environment meets the `requires_python` specification for the installed library version.fixAlways check the `requires_python` metadata for the specific cwcwidth version you intend to use and upgrade your Python environment if necessary. Consider using a virtual environment to manage dependencies.
affects: 0.1.6 and later
gotchaThe `wcwidth` and `wcswidth` functions return -1 if they encounter non-printable C0 or C1 control characters within the input string. This behavior is consistent with the underlying POSIX C functions.fixImplement checks for -1 return values, especially when processing user-generated or external string inputs, to correctly handle or filter out non-printable characters.
affects: All versions
gotchaThe library updates its internal Unicode definition periodically (e.g., version 0.1.10 updated to Unicode 15.1). This might lead to subtle changes in width calculations for certain characters if your application relies on a specific Unicode version or if the terminal's Unicode interpretation differs.fixIf precise, consistent width calculation across different environments or library versions is critical, consider pinning the `cwcwidth` version. Be aware that upgrading may alter width calculations for recently added or reclassified Unicode characters.
affects: All versions (behavior can change across updates)
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'cwcwidth'
The cwcwidth library is not installed in the current Python environment or the Python interpreter cannot find it.
fixRun `pip install cwcwidth` to install the library.
ImportError: cannot import name 'wcwidth' from 'cwcwidth' (unknown location)
The cwcwidth library is installed, but the specific function 'wcwidth' (or 'wcswidth') is not correctly imported, often due to an incorrect import statement or a corrupted installation.
fixEnsure you are using the correct import statement: `from cwcwidth import wcwidth` or `from cwcwidth import wcswidth`. If the error persists, try reinstalling the library: `pip uninstall cwcwidth && pip install cwcwidth`.
Installation failure: limits.h: No such file or directory
cwcwidth is a C extension that requires a C compiler and Python development headers (which include system header files like `limits.h`) to be present on the system for successful compilation during installation. This error typically occurs when these build tools are missing.
fixInstall the necessary build tools and Python development headers for your operating system. For Debian/Ubuntu, use `sudo apt-get install build-essential python3-dev` (replace `python3-dev` with your specific Python version if needed, e.g., `python3.x-dev`). For Fedora/RHEL, use `sudo dnf install gcc python3-devel`.
wcwidth returns -1
The `wcwidth` or `wcswidth` function, consistent with POSIX C functions, returns -1 when it encounters non-printable C0 or C1 control characters within the input string.
fixImplement checks for the -1 return value and handle or filter out non-printable characters in your input strings before passing them to `wcwidth` or `wcswidth`. For example, you might strip control characters or explicitly check if the return value is -1.
Upgrade
Version history
0.1.12latest on PyPI · released Nov 1, 2025
Audit
Dependencies
No dependency data recorded yet.