{"id":728,"library":"webcolors","title":"webcolors: HTML/CSS Color Formats","description":"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.","status":"active","version":"25.10.0","language":"python","source_language":"en","source_url":"https://github.com/ubernostrum/webcolors","tags":["color","css","html","web","rgb","hex"],"install":[{"cmd":"pip install webcolors","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"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.","symbol":"webcolors","correct":"import webcolors"}],"quickstart":{"code":"import webcolors\n\n# Convert a hex code to a color name (using CSS3/SVG names)\nhex_color = '#F08080' # Light Coral\ntry:\n    name = webcolors.hex_to_name(hex_color, spec='css3')\n    print(f\"Hex '{hex_color}' is named '{name}'.\")\nexcept ValueError as e:\n    print(f\"Could not find name for '{hex_color}': {e}\")\n\n# Convert a color name to a hex triplet\ncolor_name = 'rebeccapurple'\ntry:\n    hex_val = webcolors.name_to_hex(color_name)\n    print(f\"Color name '{color_name}' corresponds to hex '{hex_val}'.\")\nexcept ValueError as e:\n    print(f\"Could not find hex for '{color_name}': {e}\")\n\n# Convert an integer RGB triplet to a hex code\nrgb_triplet = (255, 165, 0) # Orange\nhex_from_rgb = webcolors.rgb_to_hex(rgb_triplet)\nprint(f\"RGB {rgb_triplet} converts to hex '{hex_from_rgb}'.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"1.7.0 and higher"},{"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.","message":"webcolors consistently returns 'gray' over 'grey' for the hexadecimal value #808080 (rgb(128, 128, 128), or rgb(50%, 50%, 50%)) when querying color names.","severity":"gotcha","affected_versions":"1.9.1 and higher"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Be mindful of potential minor rounding differences when performing conversions between integer and percentage RGB values, especially for values not explicitly special-cased.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T18:20:28.137Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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).","cause":"The input hexadecimal string does not conform to the expected '#RRGGBB' or '#RGB' format, or contains invalid hexadecimal digits.","error":"ValueError: '#GGG' is not a valid 3-digit or 6-digit hexadecimal color string."},{"fix":"Use a valid standard HTML/CSS color name (e.g., 'red', 'blue', 'white') or convert the color using its hexadecimal or RGB representation.","cause":"The color name provided is not one of the 147 standard HTML/CSS color names recognized by the `webcolors` library.","error":"ValueError: 'unknowncolor' is not a recognized color name."},{"fix":"Ensure all R, G, and B values in the tuple are integers within the 0 to 255 range.","cause":"One or more of the integer components in the RGB tuple are outside the valid range of 0 to 255.","error":"ValueError: R, G, B values must be between 0 and 255 (inclusive)."},{"fix":"Provide an RGB tuple with exactly three integer elements, for example, `(128, 0, 128)`.","cause":"The tuple provided for an RGB conversion function does not contain exactly three integer elements for red, green, and blue.","error":"ValueError: The rgb tuple must contain three elements."},{"fix":"Install the library using pip: `pip install webcolors`","cause":"The `webcolors` library is not installed in the current Python environment.","error":"ModuleNotFoundError: No module named 'webcolors'"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":80,"quickstart_tag":"verified","pypi_latest":"25.10.0","install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"17.9M"},{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"17.9M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"18M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.6,"disk_size":"18M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":0.9,"disk_size":"19.7M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.03,"mem_mb":0.9,"disk_size":"19.7M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.6,"import_time_s":0.02,"mem_mb":0.9,"disk_size":"20M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.9,"disk_size":"20M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"11.6M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"11.6M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.4,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"12M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.7,"disk_size":"12M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.8,"disk_size":"11.3M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.8,"disk_size":"11.2M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.5,"import_time_s":0.02,"mem_mb":0.6,"disk_size":"12M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.6,"disk_size":"12M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"17.4M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"17.4M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":" $EXIT -eq 0 ","exit_code":0,"wheel_type":"wheel","failure_reason":null,"install_time_s":1.8,"import_time_s":0.01,"mem_mb":0.5,"disk_size":"18M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.02,"mem_mb":0.5,"disk_size":"18M"}]},"quickstart_checks":{"last_tested":"2026-04-24","tag":"verified","tag_description":"quickstart runs on critical runtimes, recently tested","results":[{"runtime":"python:3.10-alpine","exit_code":0},{"runtime":"python:3.10-slim","exit_code":0},{"runtime":"python:3.11-alpine","exit_code":0},{"runtime":"python:3.11-slim","exit_code":0},{"runtime":"python:3.12-alpine","exit_code":0},{"runtime":"python:3.12-slim","exit_code":0},{"runtime":"python:3.13-alpine","exit_code":0},{"runtime":"python:3.13-slim","exit_code":0},{"runtime":"python:3.9-alpine","exit_code":0},{"runtime":"python:3.9-slim","exit_code":0}]}}