Module contents

The contents of the webcolors module fall into five categories:

  1. A set of (optional) data types for representing color values.
  2. Constants for several purposes.
  3. Normalization functions which sanitize input in various formats prior to conversion or output.
  4. Conversion functions between each method of specifying colors.
  5. Implementations of the color parsing and serialization algorithms in HTML5.

See the documentation regarding conventions for information regarding the types and representation of various color formats in webcolors.

All conversion functions which involve color names take an optional argument to determine the specification from which to draw color names. See the set of specification identifiers for valid values.

All conversion functions, when faced with identifiably invalid hexadecimal color values, or with a request to name a color which has no name in the requested specification, or with an invalid specification identifier, will raise ValueError.

Data types

Integer and percentage rgb() triplets, and HTML5 simple colors, can be passed to functions in webcolors as plain 3-tuple of the appropriate data type. But the following namedtuple() instances are also provided to represent these types more richly, and functions in webcolors which return triplets or simple colors will return instances of these:

class webcolors.IntegerRGB

A namedtuple() representing an integer RGB triplet. Has three fields, each of type int and in the range 0-255 inclusive:

red

The red portion of the color value.

green

The red portion of the color value.

blue

The red portion of the color value.

class webcolors.PercentRGB

A namedtuple() representing a percentage RGB triplet. Has three fields, each of type str and representing a percentage value in the range 0%-100% inclusive:

red

The red portion of the color value.

green

The red portion of the color value.

blue

The red portion of the color value.

class webcolors.HTML5SimpleColor

A namedtuple() representing an HTML5 simple color. Has three fields, each of type int and in the range 0-255 inclusive:

red

The red portion of the color value.

green

The red portion of the color value.

blue

The red portion of the color value.

Constants

Several sets of constants are provided in webcolors, for use when converting or identifying colors or specifications.

Specification identifiers

The following constants are available for indicating the specification from which to draw color name choices, in functions which can work with multiple specifications.

webcolors.CSS2

Represents the CSS2 specification. Value is ‘css2’.

webcolors.CSS21

Represents the CSS2.1 specification. Value is ‘css21’.

webcolors.CSS3

Represents the CSS3 specification. Value is ‘css3’.

webcolors.HTML4

Represents the HTML 4 specification. Value is ‘html4’.

Color mappings

The following constants are available for direct use in mapping from color names to values, although it is strongly recommended to use one of the normalizing conversion functions instead.

Mappings from names to hexadecimal values

webcolors.HTML4_NAMES_TO_HEX

A dict whose keys are the normalized names of the sixteen named HTML 4 colors, and whose values are the normalized hexadecimal values of those colors.

webcolors.CSS2_NAMES_TO_HEX

An alias for HTML4_NAMES_TO_HEX, as CSS2 defined the same set of colors.

webcolors.CSS21_NAMES_TO_HEX

A dict whose keys are the normalized names of the seventeen named CSS2.1 colors, and whose values are the normalized hexadecimal values of those colors (sixteen of these are identical to HTML 4 and CSS2; the seventeenth color is orange, added in CSS2.1).

webcolors.CSS3_NAMES_TO_HEX

A dict whose keys are the normalized names of the 147 named CSS3 colors, and whose values are the normalized hexadecimal values of those colors. These colors are also identical to the 147 named colors of SVG.

Mappings from hexadecimal values to names

webcolors.HTML4_HEX_TO_NAMES

A dict whose keys are the normalized hexadecimal values of the sixteen named HTML 4 colors, and whose values are the corresponding normalized names.

webcolors.CSS2_HEX_TO_NAMES

An alias for HTML4_HEX_TO_NAMES, as CSS2 defined the same set of colors.

webcolors.CSS21_HEX_TO_NAMES

A dict whose keys are the normalized hexadecimal values of the seventeen named CSS2.1 colors, and whose values are the corresponding normalized names (sixteen of these are identical to HTML 4 and CSS2; the seventeenth color is orange, added in CSS2.1).

webcolors.CSS3_HEX_TO_NAMES

A dict whose keys are the normalized hexadecimal values of the 147 named CSS3 colors, and whose values are the corresponding normalized names. These colors are also identical to the 147 named colors of SVG.

Note

Spelling variants

Some values representing named gray colors can map to either of two names in CSS3, because it supports both gray and grey spelling variants for those colors. This mapping will always return the variant spelled gray (such as lightgray instead of lightgrey). See the documentation on name conventions for details.

Normalization functions

webcolors.normalize_hex(hex_value)

Normalize a hexadecimal color value to a string consisting of the character # followed by six lowercase hexadecimal digits (what HTML5 terms a “valid lowercase simple color”).

If the supplied value cannot be interpreted as a hexadecimal color value, ValueError is raised. See the conventions used by this module for information on acceptable formats for hexadecimal values.

Examples:

>>> normalize_hex('#0099cc')
'#0099cc'
>>> normalize_hex('#0099CC')
'#0099cc'
>>> normalize_hex('#09c')
'#0099cc'
>>> normalize_hex('#09C')
'#0099cc'
>>> normalize_hex('#0099gg')
Traceback (most recent call last):
    ...
ValueError: '#0099gg' is not a valid hexadecimal color value.
>>> normalize_hex('0099cc')
Traceback (most recent call last):
    ...
ValueError: '0099cc' is not a valid hexadecimal color value.
Parameters:hex_value (str) – The hexadecimal color value to normalize.
Return type:str
Raises:ValueError – when the input is not a valid hexadecimal color value.
webcolors.normalize_integer_triplet(rgb_triplet)

Normalize an integer rgb() triplet so that all values are within the range 0..255.

Examples:

>>> normalize_integer_triplet((128, 128, 128))
IntegerRGB(red=128, green=128, blue=128)
>>> normalize_integer_triplet((0, 0, 0))
IntegerRGB(red=0, green=0, blue=0)
>>> normalize_integer_triplet((255, 255, 255))
IntegerRGB(red=255, green=255, blue=255)
>>> normalize_integer_triplet((270, -20, -0))
IntegerRGB(red=255, green=0, blue=0)
Parameters:rgb_triplet (tuple) – The integer rgb() triplet to normalize.
Return type:IntegerRGB
webcolors.normalize_percent_triplet(rgb_triplet)

Normalize a percentage rgb() triplet so that all values are within the range 0%..100%.

Examples:

>>> normalize_percent_triplet(('50%', '50%', '50%'))
PercentRGB(red='50%', green='50%', blue='50%')
>>> normalize_percent_triplet(('0%', '100%', '0%'))
PercentRGB(red='0%', green='100%', blue='0%')
>>> normalize_percent_triplet(('-10%', '-0%', '500%'))
PercentRGB(red='0%', green='0%', blue='100%')
Parameters:rgb_triplet (tuple) – The percentage rgb() triplet to normalize.
Return type:PercentRGB

Conversions from color names to other formats

webcolors.name_to_hex(name, spec=CSS3)

Convert a color name to a normalized hexadecimal color value.

The color name will be normalized to lower-case before being looked up.

Examples:

>>> name_to_hex('white')
'#ffffff'
>>> name_to_hex('navy')
'#000080'
>>> name_to_hex('goldenrod')
'#daa520'
>>> name_to_hex('goldenrod', spec=HTML4)
Traceback (most recent call last):
    ...
ValueError: 'goldenrod' is not defined as a named color in html4.
Parameters:
  • name (str) – The color name to convert.
  • spec (str) – The specification from which to draw the list of color names. Default is CSS3.
Return type:

str

Raises:

ValueError – when the given name has no definition in the given spec.

webcolors.name_to_rgb(name, spec=CSS3)

Convert a color name to a 3-tuple of int suitable for use in an rgb() triplet specifying that color.

The color name will be normalized to lower-case before being looked up.

Examples:

>>> name_to_rgb('white')
IntegerRGB(red=255, green=255, blue=255)
>>> name_to_rgb('navy')
IntegerRGB(red=0, green=0, blue=128)
>>> name_to_rgb('goldenrod')
IntegerRGB(red=218, green=165, blue=32)
Parameters:
  • name (str) – The color name to convert.
  • spec (str) – The specification from which to draw the list of color names. Default is CSS3.
Return type:

IntegerRGB

Raises:

ValueError – when the given name has no definition in the given spec.

webcolors.name_to_rgb_percent(name, spec=CSS3)

Convert a color name to a 3-tuple of percentages suitable for use in an rgb() triplet specifying that color.

The color name will be normalized to lower-case before being looked up.

Examples:

>>> name_to_rgb_percent('white')
PercentRGB(red='100%', green='100%', blue='100%')
>>> name_to_rgb_percent('navy')
PercentRGB(red='0%', green='0%', blue='50%')
>>> name_to_rgb_percent('goldenrod')
PercentRGB(red='85.49%', green='64.71%', blue='12.5%')
Parameters:
  • name (str) – The color name to convert.
  • spec (str) – The specification from which to draw the list of color names. Default is CSS3.
Return type:

PercentRGB

Raises:

ValueError – when the given name has no definition in the given spec.

Conversion from hexadecimal color values to other formats

webcolors.hex_to_name(hex_value, spec=CSS3)

Convert a hexadecimal color value to its corresponding normalized color name, if any such name exists.

The hexadecimal value will be normalized before being looked up.

Note

Spelling variants

Some values representing named gray colors can map to either of two names in CSS3, because it supports both gray and grey spelling variants for those colors. This function will always return the variant spelled gray (such as lightgray instead of lightgrey). See the documentation on name conventions for details.

Examples:

>>> hex_to_name('#ffffff')
'white'
>>> hex_to_name('#fff')
'white'
>>> hex_to_name('#000080')
'navy'
>>> hex_to_name('#daa520')
'goldenrod'
>>> hex_to_name('#daa520', spec=HTML4)
Traceback (most recent call last):
    ...
ValueError: '#daa520' has no defined color name in html4.
Parameters:
  • hex_value (str) – The hexadecimal color value to convert.
  • spec (str) – The specification from which to draw the list of color names. Default is CSS3.
Return type:

str

Raises:

ValueError – when the given color has no name in the given spec, or when the supplied hex value is invalid.

webcolors.hex_to_rgb(hex_value)

Convert a hexadecimal color value to a 3-tuple of int suitable for use in an rgb() triplet specifying that color.

The hexadecimal value will be normalized before being converted.

Examples:

>>> hex_to_rgb('#fff')
IntegerRGB(red=255, green=255, blue=255)
>>> hex_to_rgb('#000080')
IntegerRGB(red=0, green=0, blue=128)
Parameters:hex_value (str) – The hexadecimal color value to convert.
Return type:IntegerRGB
Raises:ValueError – when the supplied hex value is invalid.
webcolors.hex_to_rgb_percent(hex_value)

Convert a hexadecimal color value to a 3-tuple of percentages suitable for use in an rgb() triplet representing that color.

The hexadecimal value will be normalized before being converted.

Examples:

>>> hex_to_rgb_percent('#ffffff')
PercentRGB(red='100%', green='100%', blue='100%')
>>> hex_to_rgb_percent('#000080')
PercentRGB(red='0%', green='0%', blue='50%')
Parameters:hex_value (str) – The hexadecimal color value to convert.
Return type:PercentRGB
Raises:ValueError – when the supplied hex value is invalid.

Conversions from integer rgb() triplets to other formats

webcolors.rgb_to_name(rgb_triplet, spec=CSS3)

Convert a 3-tuple of int, suitable for use in an rgb() color triplet, to its corresponding normalized color name, if any such name exists.

To determine the name, the triplet will be converted to a normalized hexadecimal value.

Note

Spelling variants

Some values representing named gray colors can map to either of two names in CSS3, because it supports both gray and grey spelling variants for those colors. This function will always return the variant spelled gray (such as lightgray instead of lightgrey). See the documentation on name conventions for details.

Examples:

>>> rgb_to_name((255, 255, 255))
'white'
>>> rgb_to_name((0, 0, 128))
'navy'
Parameters:
  • rgb_triplet (typing.Union[IntegerRGB, Tuple[int, int, int]]) – The rgb() triplet
  • spec (str) – The specification from which to draw the list of color names. Default is CSS3.
Return type:

str

Raises:

ValueError – when the given color has no name in the given spec.

webcolors.rgb_to_hex(rgb_triplet)

Convert a 3-tuple of int, suitable for use in an rgb() color triplet, to a normalized hexadecimal value for that color.

Examples:

>>> rgb_to_hex((255, 255, 255))
'#ffffff'
>>> rgb_to_hex((0, 0, 128))
'#000080'
Parameters:rgb_triplet (typing.Union[IntegerRGB, Tuple[int, int, int]]) – The rgb() triplet.
Return type:str
webcolors.rgb_to_rgb_percent(rgb_triplet)

Convert a 3-tuple of int, suitable for use in an rgb() color triplet, to a 3-tuple of percentages suitable for use in representing that color.

Note

Floating-point precision

This function makes some trade-offs in terms of the accuracy of the final representation; for some common integer values, special-case logic is used to ensure a precise result (e.g., integer 128 will always convert to ‘50%’, integer 32 will always convert to ‘12.5%’), but for all other values a standard Python float is used and rounded to two decimal places, which may result in a loss of precision for some values due to the inherent imprecision of IEEE floating-point numbers.

Examples:

>>> rgb_to_rgb_percent((255, 255, 255))
PercentRGB(red='100%', green='100%', blue='100%')
>>> rgb_to_rgb_percent((0, 0, 128))
PercentRGB(red='0%', green='0%', blue='50%')
>>> rgb_to_rgb_percent((218, 165, 32))
PercentRGB(red='85.49%', green='64.71%', blue='12.5%')
Parameters:rgb_triplet (typing.Union[IntegerRGB, Tuple[int, int, int]]) – The rgb() triplet.
Return type:PercentRGB

Conversions from percentage rgb() triplets to other formats

webcolors.rgb_percent_to_name(rgb_percent_triplet, spec=CSS3)

Convert a 3-tuple of percentages, suitable for use in an rgb() color triplet, to its corresponding normalized color name, if any such name exists.

To determine the name, the triplet will be converted to a normalized hexadecimal value.

Note

Spelling variants

Some values representing named gray colors can map to either of two names in CSS3, because it supports both gray and grey spelling variants for those colors. This function will always return the variant spelled gray (such as lightgray instead of lightgrey). See the documentation on name conventions for details.

Examples:

>>> rgb_percent_to_name(('100%', '100%', '100%'))
'white'
>>> rgb_percent_to_name(('0%', '0%', '50%'))
'navy'
>>> rgb_percent_to_name(('85.49%', '64.71%', '12.5%'))
'goldenrod'
Parameters:
  • rgb_percent_triplet (typing.Union[PercentRGB, Tuple[str, str, str]]) – The rgb() triplet.
  • spec (str) – The specification from which to draw the list of color names. Default is CSS3.
Return type:

str

Raises:

ValueError – when the given color has no name in the given spec.

webcolors.rgb_percent_to_hex(rgb_percent_triplet)

Convert a 3-tuple of percentages, suitable for use in an rgb() color triplet, to a normalized hexadecimal color value for that color.

Examples:

>>> rgb_percent_to_hex(('100%', '100%', '0%'))
'#ffff00'
>>> rgb_percent_to_hex(('0%', '0%', '50%'))
'#000080'
>>> rgb_percent_to_hex(('85.49%', '64.71%', '12.5%'))
'#daa520'
Parameters:rgb_percent_triplet (typing.Union[PercentRGB, Tuple[str, str, str]]) – The rgb() triplet.
Return type:str
webcolors.rgb_percent_to_rgb(rgb_percent_triplet)

Convert a 3-tuple of percentages, suitable for use in an rgb() color triplet, to a 3-tuple of int suitable for use in representing that color.

Some precision may be lost in this conversion. See the note regarding precision for rgb_to_rgb_percent() for details.

Examples:

>>> rgb_percent_to_rgb(('100%', '100%', '100%'))
IntegerRGB(red=255, green=255, blue=255)
>>> rgb_percent_to_rgb(('0%', '0%', '50%'))
IntegerRGB(red=0, green=0, blue=128)
>>> rgb_percent_to_rgb(('85.49%', '64.71%', '12.5%'))
IntegerRGB(red=218, green=165, blue=32)
Parameters:rgb_percent_triplet (typing.Union[PercentRGB, Tuple[str, str, str]]) – The rgb() triplet.
Return type:IntegerRGB

HTML5 color algorithms

Warning

There are two versions of the HTML5 standard. Although they have common origins and are extremely similar, one is a living document (maintained by WHATWG) and the other is a W3C Recommendation. The functions documented below implement the HTML5 color algorithms as given in section 2.4.6 of the W3C HTML5 Recommendation.

webcolors.html5_parse_simple_color(input)

Apply the HTML5 simple color parsing algorithm.

Examples:

>>> html5_parse_simple_color('#ffffff')
HTML5SimpleColor(red=255, green=255, blue=255)
>>> html5_parse_simple_color('#fff')
Traceback (most recent call last):
    ...
ValueError: An HTML5 simple color must be a string exactly seven characters long.
Parameters:input (str, which must consist of exactly the character ‘#’ followed by six hexadecimal digits) – The color to parse.
Return type:HTML5SimpleColor
Raises:ValueError – when the given input is not a Unicode string of length 7, consisting of exactly the character # followed by six hexadecimal digits.
webcolors.html5_serialize_simple_color(simple_color)

Apply the HTML5 simple color serialization algorithm.

Examples:

>>> html5_serialize_simple_color((0, 0, 0))
'#000000'
>>> html5_serialize_simple_color((255, 255, 255))
'#ffffff'
Parameters:simple_color (typing.Union[IntegerRGB, HTML5SimpleColor, Tuple[int, int, int]], all values in the range 0..255 inclusive) – The color to serialize.
Return type:A valid lowercase simple color, which is a Unicode string exactly seven characters long, beginning with # and followed by six lowercase hexadecimal digits.
webcolors.html5_parse_legacy_color(input)

Apply the HTML5 legacy color parsing algorithm.

Note that, since this algorithm is intended to handle many types of malformed color values present in real-world Web documents, it is extremely forgiving of input, but the results of parsing inputs with high levels of “junk” (i.e., text other than a color value) may be surprising.

Examples:

>>> html5_parse_legacy_color('black')
HTML5SimpleColor(red=0, green=0, blue=0)
>>> html5_parse_legacy_color('chucknorris')
HTML5SimpleColor(red=192, green=0, blue=0)
>>> html5_parse_legacy_color('Window')
HTML5SimpleColor(red=0, green=13, blue=0)
Parameters:input (str) – The color to parse.
Return type:HTML5SimpleColor
Raises:ValueError – when the given input is not a Unicode string, or when it is precisely the string ‘transparent’.