Install & Compatibility
Where this runs
tested against v2.2.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
muslpy 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.014s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.6s · import 0.020s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Color
✓ from colorclass import Color
✗ from colorclass import ColoredString
While Color returns a ColoredString instance, users typically import and use the Color factory class directly to create colored strings.
Windows
✓ from colorclass import Windows
Required for enabling ANSI color support on Windows terminals.
list_tags
✓ from colorclass import list_tags
Use to discover all available color and style tags.
This quickstart demonstrates how to import and use the `Color` class to apply colors and styles using curly-bracket tags. It also shows how to enable Windows console support and list all available tags. The `Windows.enable()` call is conditionally applied to avoid issues in CI/CD or non-interactive environments.
from colorclass import Color, Windows, list_tags
import os
# Enable Windows console support (required for colors on Windows)
# Check if running on CI/CD or in a non-interactive environment
if os.name == 'nt' and os.environ.get('CI') != 'true' and os.isatty(1):
Windows.enable()
# Print a simple colored string
print(Color('{red}This text is red.{/red}'))
# Combine multiple colors and styles
print(Color('{autoblue}{bgwhite}Blue text on white background.{/bgwhite}{/autoblue}'))
# Use auto colors for terminals
print(Color('{autoyellow}This text adapts to terminal background.{/autoyellow}'))
# List available tags
print('\nAvailable tags:')
for tag in sorted(list_tags()):
print(f'- {tag}')
Debug
Known issues
gotchaOn Windows, ANSI color codes are not enabled by default for older terminals. You must call `Windows.enable()` in your application to properly display colors. Even on modern Windows 10/11, it's recommended for auto-color detection.fixAdd `from colorclass import Windows` and `Windows.enable()` at the start of your script if running on Windows.
affects: All versions on Windows
breakingIn Python 2.x, `colorclass` string objects subclass `unicode`, whereas in Python 3.x, they subclass `str`. This might lead to compatibility issues if your code explicitly checks types using `isinstance(obj, unicode)` or `isinstance(obj, str)` without considering the Python version.fixUse `isinstance(obj, str)` (Python 3 compatible) or `isinstance(obj, (str, unicode))` for cross-version compatibility if strict type checking is necessary. Generally, relying on duck typing is preferred.
affects: Between Python 2.x and Python 3.x environments
gotchaWhen `colorclass` is used via piped command line (`python -m colorclass`), environment variables like `COLOR_DISABLE=true` or `COLOR_ENABLE=true` can override automatic color detection, forcing colors off or on, respectively.fixBe aware of these environment variables (`COLOR_DISABLE`, `COLOR_ENABLE`) if colors are not appearing as expected in piped contexts. They take precedence over other settings.
affects: All versions when used via command line pipe
Errors
Common errors & fixes
ImportError: cannot import name 'Mapping' from 'collections'
In Python 3.10+, `collections.Mapping` was moved to `collections.abc.Mapping`. Older versions of `colorclass` directly imported `Mapping` from `collections`, leading to this error on newer Python versions.
fixUpgrade the `colorclass` library to version 2.2.2 or newer, which addresses this compatibility issue. `pip install --upgrade colorclass`
AttributeError: 'str' object has no attribute 'decode'
This error occurs when attempting to call the `.decode()` method on a `str` object in Python 3. In Python 3, strings are Unicode by default, and `colorclass.Color` instances subclass `str`, meaning explicit decoding is unnecessary and the method does not exist. This is a common migration issue from Python 2 where `str` objects were bytes and needed decoding.
fixRemove the `.decode()` call from the `Color` object or string. If you intend to convert bytes to a string, ensure the object is actually a `bytes` object first (e.g., `my_bytes_data.decode('utf-8')`). NameError: name 'Windows' is not defined
Users often forget to explicitly import the `Windows` object from the `colorclass` library when trying to enable Windows console support. While `Color` is commonly imported, `Windows` needs its own import statement.
fixEnsure `Windows` is imported from `colorclass` alongside `Color`. Add `from colorclass import Windows` (or `from colorclass import Color, Windows`) to your script before calling `Windows.enable()`.
AttributeError: module 'colorclass' has no attribute 'Windows'
This error occurs if a user tries to access `Windows` directly as an attribute of the `colorclass` module (e.g., `colorclass.Windows.enable()`) instead of importing it explicitly or accessing it from the correct submodule path if not imported.
fixImport the `Windows` class directly from the `colorclass` library: `from colorclass import Windows`. Then, call `Windows.enable()`.
Upgrade
Version history
2.2.2latest on PyPI · released Dec 9, 2021
Audit
Dependencies
No dependency data recorded yet.