---
id: cwcwidth
version: "0.1.12"
license: MIT
license_treatment: permissive
maintenance: active
---

# cwcwidth — Python bindings for wc(s)width

License: permissive · Maintenance: active · Downloads: 575.9K/mo

## What it is and what it does

cwcwidth is a C-based Python library that calculates how many columns a Unicode string will occupy when displayed in a terminal. It wraps POSIX wcwidth/wcswidth functions (or Markus Kuhn's implementation on non-POSIX systems) and provides the same API as the pure-Python wcwidth package, but with significantly faster execution through Cython compilation.

The library is useful when you need accurate terminal rendering calculations—for instance, when aligning text in CLI tools, formatting table output, or handling mixed-width characters (like CJK ideographs that occupy two columns). It has no runtime dependencies and supports modern Python versions (3.11+) across major platforms with prebuilt wheels.

Use it for:

- Calculate display width of strings containing East Asian characters for terminal table formatting.
- Align text output in CLI applications where mixed-width characters must be handled correctly.
- Truncate or pad Unicode strings to fit within a specific terminal column width.
- Build terminal UI libraries that need accurate character width calculations for layout.
- Validate or measure string display length in text processing pipelines.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

cwcwidth provides fast Python bindings for POSIX wcwidth and wcswidth functions to compute the printable display width of Unicode characters and strings on terminals.

Yes, if you need fast Unicode display-width calculations for terminal output. The library is actively maintained, has no security vulnerabilities, carries a permissive license, and offers substantial performance gains over pure-Python alternatives. Install friction is moderate but manageable with prebuilt wheels for all major platforms. Requires Python 3.11+.

## Install

pip install cwcwidth
uv add cwcwidth
poetry add cwcwidth

## Installing cwcwidth

Before you install: Medium install friction due to compiled wheels, but well-supported across platforms (macOS arm64/x86_64, Linux x86_64/aarch64, Windows 32/64-bit, musl). Active maintenance with recent release.

License in practice: MIT license is permissive; you can use, modify, and distribute cwcwidth freely with minimal restrictions.

Quickstart:

pip install cwcwidth

import cwcwidth
print(cwcwidth.wcwidth('a'))  # 1
print(cwcwidth.wcswidth('コンニチハ, セカイ!'))  # 19

Requires Python 3.11 or later.

Verify before relying:

- Whether performance improvement over wcwidth remains significant in real-world terminal applications beyond the benchmark shown.
- Whether the limited Python API mode (via USE_LIMITED_API environment variable) affects performance or compatibility.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 575.9K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

unicode character display width, terminal string width calculation, wcwidth python bindings, east asian character width, terminal column width, unicode display length, wcswidth implementation, unicode-handling, terminal-ui, performance-critical

[View on SkillFed](https://skillfed.io/packages/cwcwidth) · [View on PyPI](https://pypi.org/project/cwcwidth/)