webcolors: HTML/CSS Color Formats

25.10.0 verified Tue May 12 auth: no python install: verified quickstart: verified

webcolors is a Python library designed for working with and converting between various HTML/CSS color formats. It provides functions to normalize and convert between specification-defined color names, six-digit hexadecimal, three-digit hexadecimal, and integer and percentage rgb() triplets, focusing exclusively on the RGB color space. The current version is 25.10.0, and the project maintains an active release cadence with updates typically several times a year.

pip install webcolors

Common errors

error ValueError: '#GGG' is not a valid 3-digit or 6-digit hexadecimal color string. ↓

cause The input hexadecimal string does not conform to the expected '#RRGGBB' or '#RGB' format, or contains invalid hexadecimal digits.

fix

Provide a valid 3-digit or 6-digit hexadecimal color string, ensuring it starts with '#' and contains only hexadecimal characters (0-9, A-F, a-f).

error ValueError: 'unknowncolor' is not a recognized color name. ↓

cause The color name provided is not one of the 147 standard HTML/CSS color names recognized by the `webcolors` library.

fix

Use a valid standard HTML/CSS color name (e.g., 'red', 'blue', 'white') or convert the color using its hexadecimal or RGB representation.

error ValueError: R, G, B values must be between 0 and 255 (inclusive). ↓

cause One or more of the integer components in the RGB tuple are outside the valid range of 0 to 255.

fix

Ensure all R, G, and B values in the tuple are integers within the 0 to 255 range.

error ValueError: The rgb tuple must contain three elements. ↓

cause The tuple provided for an RGB conversion function does not contain exactly three integer elements for red, green, and blue.

fix

Provide an RGB tuple with exactly three integer elements, for example, (128, 0, 128).

error ModuleNotFoundError: No module named 'webcolors' ↓

cause The `webcolors` library is not installed in the current Python environment.

fix

Install the library using pip: pip install webcolors

Warnings

breaking Python 2.x support was dropped, and string arguments on Python 3 became strictly `str` (Unicode), not `bytes`. Attempting to use `bytes` will raise an exception. ↓

fix Ensure all string-based color inputs (hex codes, color names, percentage RGB strings) are Python 3 `str` objects. Migrate any Python 2 code using `webcolors` to Python 3 and update string handling.

gotcha webcolors consistently returns 'gray' over 'grey' for the hexadecimal value #808080 (rgb(128, 128, 128), or rgb(50%, 50%, 50%)) when querying color names. ↓

fix Be aware that `webcolors` normalizes to the American spelling 'gray' for consistency with older HTML/CSS standards. If you require 'grey', you will need to map it manually after conversion.

gotcha The library exclusively handles RGB color values and does not support alpha channels (transparency), such as `rgba()` or `#rrggbbaa` formats. Conversion to/from HSL is also not directly supported by `webcolors` itself. ↓

fix If alpha channel support or HSL conversions are needed, consider using other libraries in conjunction with `webcolors`, such as Python's standard `colorsys` module for HSL/HSV conversions.

gotcha Conversions involving percentage `rgb()` triplets (`rgb_to_rgb_percent()` and `rgb_percent_to_rgb()`) may exhibit floating-point imprecision for certain values due to the nature of IEEE floating-point arithmetic. Common values (0, 16, 32, 64, 128, 255) are special-cased for precision, but others are rounded to two decimal places. ↓

fix Be mindful of potential minor rounding differences when performing conversions between integer and percentage RGB values, especially for values not explicitly special-cased.

gotcha The library's named color definitions, particularly for 'css3', may not encompass all named colors introduced in later CSS specifications (e.g., CSS Color Module Level 4). Colors like 'rebeccapurple' may not be recognized, leading to a `ValueError`. ↓

fix Verify the exact set of named colors supported by the `webcolors` library (e.g., by inspecting `webcolors.css3_names_to_hex`). If a required named color is not present, convert it to a hex or RGB value using another method before passing it to `webcolors` functions, or manually extend the `webcolors` color dictionaries if appropriate.

gotcha The library supports specific sets of named colors (e.g., CSS3, HTML4.01). Newer named colors defined in later CSS specifications (such as 'rebeccapurple' from CSS Color Module Level 4) are not recognized by default, and attempts to convert them will result in a `ValueError` indicating the color is not defined. ↓

fix If support for newer or custom named colors is required, users must either manually define and map these colors or consider using a different library that includes a more extensive or customizable set of named color definitions.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) wheel - 0.01s 17.9M

3.10 alpine (musl) - - 0.01s 17.9M

3.10 slim (glibc) wheel 1.5s 0.01s 18M

3.10 slim (glibc) - - 0.01s 18M

3.11 alpine (musl) wheel - 0.03s 19.7M

3.11 alpine (musl) - - 0.03s 19.7M

3.11 slim (glibc) wheel 1.6s 0.02s 20M

3.11 slim (glibc) - - 0.02s 20M

3.12 alpine (musl) wheel - 0.02s 11.6M

3.12 alpine (musl) - - 0.02s 11.6M

3.12 slim (glibc) wheel 1.4s 0.02s 12M

3.12 slim (glibc) - - 0.02s 12M

3.13 alpine (musl) wheel - 0.02s 11.3M

3.13 alpine (musl) - - 0.02s 11.2M

3.13 slim (glibc) wheel 1.5s 0.02s 12M

3.13 slim (glibc) - - 0.02s 12M

3.9 alpine (musl) wheel - 0.01s 17.4M

3.9 alpine (musl) - - 0.01s 17.4M

3.9 slim (glibc) wheel 1.8s 0.01s 18M

3.9 slim (glibc) - - 0.02s 18M

Imports

webcolors
```
import webcolors
```
All functions are available directly under the top-level `webcolors` module. Importing from submodules (e.g., `from webcolors.html5 import name_to_hex`) is not officially supported and may break in future versions due to internal reorganizations.

Quickstart verified last tested: 2026-04-24

This quickstart demonstrates common conversions between hexadecimal color codes, color names (using CSS3/SVG specification), and integer RGB triplets. It includes error handling for cases where a direct color name match might not exist.

import webcolors

# Convert a hex code to a color name (using CSS3/SVG names)
hex_color = '#F08080' # Light Coral
try:
    name = webcolors.hex_to_name(hex_color, spec='css3')
    print(f"Hex '{hex_color}' is named '{name}'.")
except ValueError as e:
    print(f"Could not find name for '{hex_color}': {e}")

# Convert a color name to a hex triplet
color_name = 'rebeccapurple'
try:
    hex_val = webcolors.name_to_hex(color_name)
    print(f"Color name '{color_name}' corresponds to hex '{hex_val}'.")
except ValueError as e:
    print(f"Could not find hex for '{color_name}': {e}")

# Convert an integer RGB triplet to a hex code
rgb_triplet = (255, 165, 0) # Orange
hex_from_rgb = webcolors.rgb_to_hex(rgb_triplet)
print(f"RGB {rgb_triplet} converts to hex '{hex_from_rgb}'.")