{"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,"search_vec":"'0.6.0':30 '2022':35 '22':34 'accur':23 'activ':39 'approxim':46 'cadenc':44 'current':27 'display':14 'ensur':22 'everi':47 'format':25 'januari':33 'librari':10,37 'maintain':40 'measur':5,12 'month':49 'python':9,54 'releas':31,43 'string':3,18,51 'termin':21,53 'text':24 'unicod':2,17,50 'version':28 'wcwidth':1,6 'width':4,15,52","created_at":"2026-03-28T10:52:57.544489+00:00","updated_at":"2026-04-17T00:30:05.256714+00:00","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,"quickstart_score":0,"quickstart_tag":"stale","pypi_latest":"0.8.2","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/jquast/wcwidth","docs":null,"changelog":null,"pypi":"https://pypi.org/project/wcwidth/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-08-27","next_check":"2026-07-28","install_tag":"verified"}}