A Python client library for generating URLs with imgix
Python 36 a year ago imgix/imgix-python


pip install imgix


To begin creating imgix URLs, import the imgix library and create a URL builder. The URL builder can be reused to create URLs for any images on the domains it is provided.

>>> from imgix import UrlBuilder
>>> ub = UrlBuilder("")
>>> ub.create_url("bridge.png", {'w': 100, 'h': 100})

HTTPS support is enabled by default. HTTP can be toggled on by setting use_https to False:

>>> from imgix import UrlBuilder
>>> ub = UrlBuilder("", use_https=False)
>>> ub.create_url("/bridge.png", {'w': 100, 'h': 100})

Signed URLs

To produce a signed URL, you must enable secure URLs on your source and then provide your signature key to the URL builder.

>>> from imgix import UrlBuilder
>>> ub = UrlBuilder("", sign_key="test1234")
>>> ub.create_url("/bridge.png", {'w': 100, 'h': 100})

Disabled Path Encoding

Path encoding is enabled by default. It can be toggled off by setting disable_path_encoding to True in the optional options paramater in create_url() and create_srcset() functions:

>>> from imgix import UrlBuilder
>>> ub = UrlBuilder("")
>>> ub.create_url(" <>[]{}|^%.jpg", params={'w': 100, 'h': 100}, options={'disable_path_encoding': True})
' <>[]{}|^%.jpg?h=100&w=100'

Normally this would output a source URL like, but since path encoding is disabled, it will output a source URL like <>[]{}|^%.jpg?h=100&w=100.

>>> from imgix import UrlBuilder
>>> ub = UrlBuilder("")
>>> ub.create_srcset("image<>[]{} 123.png", widths=[100], options={'disable_path_encoding': True})
'<>[]{} 123.png?w=100 100w'

Normally this would output a source URL like 100w, but since path encoding is disabled, it will output a source URL like<>[]{} 123.png?w=100 100w.

Srcset Generation

The imgix-python package allows for generation of custom srcset attributes, which can be invoked through the create_srcset method. By default, the generated srcset will allow for responsive size switching by building a list of image-width mappings.

import os
from imgix import UrlBuilder

# Keep Your Secrets Safe!
SECRET = os.getenv("IX_SIGN_KEY")
ub = UrlBuilder("", sign_key=SECRET)
srcset = ub.create_srcset("image.png")

The above will produce the following srcset attribute value which can then be served to the client: 100w, 116w, 135w,
                                        ... 7401w, 8192w

Fixed-Width Images

In cases where enough information is provided about an image's dimensions, create_srcset will instead build a srcset that will allow for an image to be served at different resolutions. The parameters taken into consideration when determining if an image is fixed-width are w, h, and ar.

By invoking create_srcset with either a width or the height and aspect ratio (along with fit=crop, typically) provided, a different srcset will be generated for a fixed-width image instead.

from imgix import UrlBuilder
>>> ub = UrlBuilder("", sign_key="my-token")
>>> srcset = ub.create_srcset("image.png", {'h':800, 'ar':'3:2', 'fit':'crop'})

Will produce the following attribute value: 1x, 2x, 3x, 4x, 5x

By default, this library generates a srcset with pixel density values of 1 through 5. These target ratios can be controlled by using the devicePixelRatios parameters.

from imgix import UrlBuilder
client = UrlBuilder("")
  { "w": 100 },
    "device_pixel_ratios": [ 1, 2, 3 ]

Will produce the following attribute value: 1x, 2x, 3x'

For more information to better understand srcset, we highly recommend Eric Portis' "Srcset and sizes" article which goes into depth about the subject.

Variable Quality

This library will automatically append a variable q parameter mapped to each dpr parameter when generating a fixed-width image srcset. This technique is commonly used to compensate for the increased file size of high-DPR images.

Since high-DPR images are displayed at a higher pixel density on devices, image quality can be lowered to reduce overall file size––without sacrificing perceived visual quality. For more information and examples of this technique in action, see this blog post.

This behavior will respect any overriding q value passed in as a parameter. Additionally, it can be disabled altogether by passing disable_variable_quality = true to create_srcset.

This behavior specifically occurs when a fixed-width image is rendered, for example:

# Note that `params={"w": 100}` allows `create_srcset` to _infer_ the creation
# of a DPR based srcset attribute for fixed-width images.
ub = imgix.UrlBuilder('')
# Set `disable_variable_quality` to True to disable variable quality.
srcset = ub.create_srcset('image.jpg', params={"w": 100}, disable_variable_quality=False)

The above will generate a srcset with the following q to dpr query params: 1x, 2x, 3x, 4x, 5x

By default, this library will automatically append a variable q parameter mapped to each dpr parameter when generating a fixed-width image srcset.

To customize variable qualities, you can pass a variable_qualities dictionary in the options while creating srcset as below:

from imgix import UrlBuilder
client = UrlBuilder("")
client.create_srcset("image.jpg", {"w": 100}, {"variable_qualities": {1: 45, 2: 30, 3: 20, 4: 15, 5: 10}})

The above script will produce the following output: 1x 2x 3x 4x 5x

You can also pass variable_qualities along with the device_pixel_ratios option as below:

from imgix import UrlBuilder
client = UrlBuilder("")
  { "w": 100 },
    "device_pixel_ratios": [ 1, 2, 3 ],
    "variable_qualities": { 1: 45, 2: 30, 3: 20 }

The above script will produce the following output: 1x, 2x, 3x

Fluid-Width Images

Custom Widths

In situations where specific widths are desired when generating srcset pairs, a user can specify them by passing an array of positive integers as widths:

>>> from imgix import UrlBuilder
>>> builder = UrlBuilder('')
>>> builder.create_srcset('image.jpg', widths=[144, 240, 320, 446, 640])
' 144w,\n 240w,\n 320w,\n 446w,\n 640w' 144w, 240w, 320w, 446w, 640w

Note: in situations where a srcset is being rendered as a fixed-width srcset, any custom widths passed in will be ignored.

Additionally, if both widths and a width tolerance are passed to the create_srcset method, the custom widths list will take precedence.

Width Ranges

In certain circumstances, you may want to limit the minimum or maximum value of the non-fixed srcset generated by the create_srcset method. To do this, you can specify the widths at which a srcset should start and stop:

>>> from imgix import UrlBuilder
>>> ub = UrlBuilder('')
>>> ub.create_srcset('image.jpg', start=500, stop=2000)
' 500w,\n 580w,\n 673w,\n 780w,\n 905w,\n 1050w,\n 1218w,\n 1413w,\n 1639w,\n 1901w,\n 2000w'

Formatted version of the above srcset attribute: 500w, 580w, 673w, 780w, 905w, 1050w, 1218w, 1413w, 1639w, 1901w, 2000w'

Width Tolerance

The srcset width tolerance dictates the maximum tolerated difference between an image's downloaded size and its rendered size.

For example, setting this value to 0.10 means that an image will not render more than 10% larger or smaller than its native size. In practice, the image URLs generated for a width-based srcset attribute will grow by twice this rate.

A lower tolerance means images will render closer to their native size (thereby increasing perceived image quality), but a large srcset list will be generated and consequently users may experience lower rates of cache-hit for pre-rendered images on your site.

By default, srcset width tolerance is set to 0.08 (8 percent), which we consider to be the ideal rate for maximizing cache hits without sacrificing visual quality. Users can specify their own width tolerance by providing a positive scalar value as width tolerance:

>>> import imgix
>>> ub = imgix.UrlBuilder('')
>>> srcset = ub.create_srcset('image.jpg', start=100, stop=384, tol=0.20)

In this case, the width_tolerance is set to 20 percent, which will be reflected in the difference between subsequent widths in a srcset pair: 100w, 140w, 196w, 274w, 384w

Explore Target Widths

The target_widths function is used internally to generate lists of target widths to be used in calls to create_srcset.

It is a way to generate, play with, and explore different target widths separately from srcset attributes. One way of generating a srcset attribute is:

srcset = ub.create_srcset('image.jpg', start=300, stop=3000, tol=0.13)

The above is convenient if start, stop, and tolerance are known in advance. Another approach is to use target_widths to determine which combination of values for start, stop, and tolerance work best.

>>> from imgix import UrlBuilder, target_widths
>>> # Create
>>> widths = target_widths(300, 3000, 0.13)
>>> widths
[300, 378, 476, 600, 756, 953, 1200, 1513, 1906, 2401, 3000]
>>> # Explore
>>> sm, md, lg = widths[:3], widths[3:7], widths[7:]
>>> widths = [w for w in widths[1::2]]
>>> widths
[378, 600, 953, 1513, 2401]
>>> # Serve
>>> ub = UrlBuilder('')
>>> srcset = ub.create_srcset('image.png', widths=widths)
>>> srcset
' 378w,\n 600w,\n 953w,\n 1513w,\n 2401w'

Usage with UTF-8

For usage with non-ASCII characters, please be sure that your project's source files specify UTF-8 encoding:

# -*- coding: utf-8 -*-

If you don't add this encoding, and you have an image with the name 'tiburón.jpeg', for example, you will get the following error trying to run your script:

SyntaxError: Non-ASCII character '***' in file on line 6, but no encoding declared; see for details

The ixlib Parameter

For security and diagnostic purposes, we sign all requests with the language and version of library used to generate the URL.

This can be disabled by setting include_library_param to False like so:

UrlBuilder('', include_library_param=False)


Run the following to execute the project's tests and code linter:


If you have cloned this repo or downloaded it locally, you can also run python -m doctest -v to test the examples in this readme.


FOSSA Status

More Core Libraries