Install & Compatibility
Where this runs
tested against v25.10.0 · 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.018s · 17.9MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 1.5s · import 0.016s · 18MB
16MB installed
● package 16MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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.
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}'.")
Debug
Known issues
breakingPython 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.fixEnsure 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.
affects: 1.7.0 and higher
gotchawebcolors consistently returns 'gray' over 'grey' for the hexadecimal value #808080 (rgb(128, 128, 128), or rgb(50%, 50%, 50%)) when querying color names.fixBe 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.
affects: 1.9.1 and higher
gotchaThe 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.fixIf 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.
affects: All versions
gotchaConversions 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.fixBe mindful of potential minor rounding differences when performing conversions between integer and percentage RGB values, especially for values not explicitly special-cased.
affects: All versions
gotchaThe 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`.fixVerify 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.
affects: All versions
gotchaThe 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.fixIf 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.
affects: All versions
Errors
Common errors & fixes
ValueError: '#GGG' is not a valid 3-digit or 6-digit hexadecimal color string.
The input hexadecimal string does not conform to the expected '#RRGGBB' or '#RGB' format, or contains invalid hexadecimal digits.
fixProvide 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).
ValueError: 'unknowncolor' is not a recognized color name.
The color name provided is not one of the 147 standard HTML/CSS color names recognized by the `webcolors` library.
fixUse a valid standard HTML/CSS color name (e.g., 'red', 'blue', 'white') or convert the color using its hexadecimal or RGB representation.
ValueError: R, G, B values must be between 0 and 255 (inclusive).
One or more of the integer components in the RGB tuple are outside the valid range of 0 to 255.
fixEnsure all R, G, and B values in the tuple are integers within the 0 to 255 range.
ValueError: The rgb tuple must contain three elements.
The tuple provided for an RGB conversion function does not contain exactly three integer elements for red, green, and blue.
fixProvide an RGB tuple with exactly three integer elements, for example, `(128, 0, 128)`.
ModuleNotFoundError: No module named 'webcolors'
The `webcolors` library is not installed in the current Python environment.
fixInstall the library using pip: `pip install webcolors`
Upgrade
Version history
25.10.0latest on PyPI · released Oct 31, 2025
Audit
Dependencies
No dependency data recorded yet.