{"id":379,"library":"wcwidth","title":"wcwidth: Unicode String Width Measurement","description":"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.","status":"active","version":"0.6.0","language":"python","source_language":"en","source_url":"https://github.com/jquast/wcwidth","tags":["Unicode","String Width","Terminal","Python"],"install":[{"cmd":"pip install wcwidth","lang":"bash","label":"Install wcwidth"}],"dependencies":[],"imports":[{"note":"Ensure correct import path to access the wcwidth function","symbol":"wcwidth","correct":"from wcwidth import wcwidth"}],"quickstart":{"code":"from wcwidth import wcwidth\n\n# Measure the width of a Unicode string\ntext = 'Hello, 世界'\nwidth = wcwidth(text)\nprint(f'The width of the text is: {width}')","lang":"python","description":"This example demonstrates how to import the wcwidth function and use it to measure the width of a Unicode string."},"warnings":[{"fix":"Update your code to be compatible with Unicode version 17.0.0 and remove any reliance on the 'unicode_version' keyword.","message":"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.","severity":"breaking","affected_versions":"0.5.0"},{"fix":"Remove the 'unicode_version' keyword from your wcwidth() function calls.","message":"The 'unicode_version' keyword in wcwidth() functions was deprecated in version 0.5.0 and is ignored in version 0.6.0.","severity":"deprecated","affected_versions":"0.5.0, 0.6.0"},{"fix":"Regularly test your application with diverse Unicode characters to identify and handle any width measurement issues.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"The wcwidth() function expects a single Unicode character as input. Passing a multi-character string will result in a TypeError.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T13:25:28.760Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"fix":"pip install wcwidth","cause":"The 'wcwidth' library has not been installed in your current Python environment.","error":"ModuleNotFoundError: No module named 'wcwidth'"},{"fix":"from wcwidth import wcwidth","cause":"The 'wcwidth' function or module was called without being imported first.","error":"NameError: name 'wcwidth' is not defined"},{"fix":"Pass only a single character to `wcwidth.wcwidth()`, or use `wcwidth.wcswidth()` for an entire string.","cause":"The 'wcwidth.wcwidth' function expects a single Unicode character string as input, but it received a string containing multiple characters.","error":"TypeError: expected a character, got 'some_string'"},{"fix":"Ensure the input to `wcwidth.wcwidth()` is always a single Unicode character string.","cause":"The 'wcwidth.wcwidth' function expects a single Unicode character string as input, but it received a non-string type like an integer.","error":"TypeError: expected a character, got <class 'int'>"},{"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()`.","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.","error":"wcwidth returns -1"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"18.3M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":1.7,"disk_size":"19M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.08,"mem_mb":1.8,"disk_size":"20.1M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.8,"disk_size":"21M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.6,"disk_size":"12.0M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.6,"disk_size":"13M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.7,"disk_size":"11.6M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.06,"mem_mb":1.5,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"17.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.04,"mem_mb":1.7,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}