Adaptive Images

Deliver small images to small devices

Download the latest version (1.5.2)

Thanks for your interest! If you have problems please check the GitHub repository.

Other versions

Adaptive Images is intended to be useable on any website, but there are a number of ports that other people have done to make things easier if you're running a particular CMS, or if you're not a PHP kind of person.

I do not have anything to do with these other versions, they may be based on out-of-date version of Adaptive Images, or may not work at all. Investigate for yourself.

If you have a port you'd like listed here, please get in touch. I'd particularly love to know about any nginx or ruby ports as a number of people have contacted me for these.


Version 1.5.2

Bug Fix

  1. AI was not generating high DPI images larger than the existing maximum $resolutions value.

    I had used a < when I needed a >. That is now fixed. If AI detects retina displays it is now able to generate larger images than the top bounds set in $resolutions.

Version 1.5.1


  1. JPGs are now created as Progressive rather than Optimised.

    Progressive JPGs are actually slightly smaller in file-size than Optimised JPGs, and have the benefit of appearing to load faster in modern browsers (they download in passes, gradually getting sharper).

Version 1.5


  1. Much improved support for Retina and other high DPI devices

    NOTE: Retina support requires using alternate JavaScript: <script>document.cookie='resolution='+Math.max(screen.width,screen.height)+("devicePixelRatio" in window ? ","+devicePixelRatio : ",1")+'; path=/';</script>

    NOTE: If you see folders in the ai-cache directory which are larger than any defined in your $resolutions array, it is because someone with a high DPI / Retina display visited your site, and AI was able to generate the required image for them.


    Previous AI behaviour meant that supporting Retina required adding very high values in the $resolutions array. This is sub-optimal because:

    1) This array is meant to be nothing more than the same values as your media query breakpoints. Adding larger ones isn't intuitive.
    2) When no cookie is set, AI sends non-mobile devices the largest $resolution value, which in that case could be far too large for most people (2000px+)

    AI is now much smarter, you do not need to edit the $resolutions array; just leave that as your CSS MQ sizes.

    AI now auto-detects the pixel density of any high DPI device and either picks a matching size from the existing array, or creates new high-dpi images which are multiples of your chosen $resolutions values.

  2. Updated documentation

    See the instructions.htm file included with the download.

Version 1.4.1


  1. More helpful error messages if something goes wrong.

  2. Updated the documentation a little.

Version 1.4


  1. Auto-creates the ai-cache folder with the correct permissions.

    No need to manually create the ai-cache folder any more, AI does it for you, which makes installation a two step process: upload files, add JS to the head.

Bug Fix

  1. Fixed an incorrect permission on created files, they're now 755 not 777.

Version 1.3.9


  1. Better detection of mobile device in the event cookies are not available.

    If cookies are unavailable AI resorts to basic UA sniffing.

    Previously AI assumed all devices are mobile and searched the UA string for a desktop OS. If found it overrode $mobile_first. However, this meant tablet devices got mobile sized images as their OS is not a desktop OS.

    Now switched to assume the device is a desktop, but AI searches the UA string for 'mobile' to switch to mobile first. All current mobile browsers behave in this way, meaning mobiles still get mobile resolution, but tablets and desktop get the largest configured resolution.

  2. Removed $mobile_first as it is no longer needed (see above)

Thanks to Gerv for contributions to this update.

Version 1.3.8

Bug Fixes

  1. Eliminated occasional double-slash in $cache_file path due to $requested_uri sometimes starting with a /

Version 1.3.7

Bug Fixes

  1. A stupid mistake was causing the browser detect to always return false. This has been fixed.

    With this update Adaptive Images now detects if a user is running on a desktop OS and switches $mobile_first to FALSE in that case. This means that if no cookie is set and $mobile_first is TRUE the following will happen:

    • On a mobile phone, the mobile sized image will be delivered.
    • On a desktop, the highest resolution configured will be delivered.

    If a cookie is set, Adaptive Images will use the cookie value to determine the correct size image to send.

Version 1.3.6


  1. Added Linux desktop detection to the $mobile_first check routine (see previous changelog details)

Version 1.3.5

New Feature

  1. To work around browser issues with unreliable cookie setting speed Adaptive Images now also checks the user agent string.

    If a desktop environment is detected, $mobile_first is automatically over-ridden to "FALSE". If not Adaptive Images will obey the configured value.

    This is a safety fallback and requires testing before I revert the default $mobile_first configured value to TRUE.

Version 1.3.4

Bug Fixes

  1. URLs are now allowed to have spaces and other encoded characters in them

  2. The sharpening function broke on libraries not compiled with the bundled version of PHP/GD.

    Adaptive Images now tests the imageconvolution function is available and gracefully handles cases where it isn't.

New Features

  1. Instructions to take advantage of high-density displays like Apple's iPhone4 are now included.

    Just use the alternative JavaScript snippet.


  1. Set $mobile_first default value to FALSE.

    Browsers are inconsistent with their ability to set cookies before requesting <img>s. For more information visit Preloaders, cookies, and race-conditions.

Version 1.3.3

Bug Fixes

  1. Added Gecko to the auto-disabled $mobile_first check: IE and Firefox don't honour $mobile_first.

    This is because both suffer from a race condition when setting the cookie. Sometimes it's set before <img> are requested, sometimes not. This could produce desktop websites with mobile versions on first page load.

Other Improvements

  1. Changed the HTTP Cache Header from "public" to "private".

    This allows caches that are specific to one user (e.g., browser cache) to store the image in cache; shared caches (e.g., a proxy server) won't. This should avoid people behind proxies or other caching mechanisms experiencing wrongly sized images.

Version 1.3.2

Bug Fixes

  1. Internet Explorer was not correctly setting the cookie, and thus breaking badly.

  2. Fixed a possible Cookie Injection, and optimised ai-cookie.php


In testing it seems that Firefox is now behaving properly and setting the cookie in time. With that being the case I've re-instated support for $mobile_first = TRUE on that browser.

Thanks to Oncle Tom for contributions to this update.

Version 1.3.1

Bug Fixes

  1. PNGs now maintain their alpha transparency when scaled down

    Previously got black backgrounds where transparency should be.

Thanks to Emilio Bravo for contributions to this update.

Version 1.3

New Features

  1. Finalised $mobile_first behaviour and defaulted it to TRUE.

Bug Fixes

  1. Fixed typo which incorrectly set browser cache.

Other Improvements

  1. When $mobile_first is FALSE now sends highest configured size instead of original source file

  2. Refactored the PHP to be more robust and efficient

  3. Simplified the JS to a single line and fixed pollution of the global namespace

  4. Made the .htaccess rule more robust and accurate


Firefox will not honour $mobile_first as set in the CONFIG section. This is intentional, and required due to an apparent defect in Firefox's behaviour. It does not set cookies fast enough, and therefor on the first visit to a site would load the mobile sized image even if JS was enabled. Therefor, AI will not honour the $mobile_first setting on Firefox based browsers that have JavaScript disabled.

Thanks to Jordi Boggiano for contributions to this update.

Version 1.3 beta

New Features

  1. Added support for Mobile First philosophy (see CONFIG, $mobile_first)


When $mobile_first is set to TRUE it means the mobile sized version of the requested image will be sent in the event that no cookie is set (likely because JavaScript is unavailable). If FALSE, the original image is sent.

There seems to be a problem with Firefox on a first visit to a site where $mobile_first is TRUE. It doesn't set the cookie fast enough, so the very first load sends the mobile size image. All page loads after are fine. Opera, Safari, and Chrome all work OK.

Version 1.2.2

New Features

  1. Unsupported no-javascript solution (see instructions.htm in the download zip)

    This allows a cookie to be set using a bogus image request to a PHP file from a CSS media query.

Version 1.2.1

No new features

I have re-branded Responsive-Images to "Adaptive-Images", firstly to help distinguish this project from the identically named project by Filament Group, and secondly because it's a more appropriate name. This system actively adapts existing images as well as "responding" to the visitors viewport to serve an appropriately sized version.


The project is now available on GitHub for those who wish to track it there:

Version 1.2

New features

  1. Support for PNG and GIF images

  2. Added ability to sharpen re-scaled images (see CONFIG, $sharpen)

Bug Fixes

  1. Better extension detection (.jpeg was failing)

  2. First-run Firefox bug fixed. The JS must be in-line, in the <head>

    Firefox (and potentially others, but not observed anywhere else) was requesting the first <img> before it loaded the external javascript file, even when in the <head>. This caused Firefox to load the full-resolution image the very first time the site was visited. All subsequent page views were fine.

Other improvements

  1. Cleaned up the .htaccess file and included clear comments on use

  2. Vastly improved instructions and examples on the downloadable zip

  3. Since 1.1 fixed issues with browser cache, default cache time now set to 7 days

  4. Refactored PHP code

Thanks to Fabian Beiner for contributions to this update

Version 1.1

New features

  1. Re-engineered the size detection methodology.

    Now detects maximum possible screen size of the device instead of the current window size. This removes the problem of visitors with small windows caching small images to the browser, then upon maximising the browser having too small images for the new screen size. It also simplifies the JS back down to its original "just dump the size into a cookie" functionality.

    This update removes all JS config options.

Version 1

New features

  1. Headers sent along with the image, for browser side caching (see CONFIG, $browser_cache)

  2. JavaScript responds to window re-sizes, requests higher res images if required

Bug fixes

  1. Fixed the MIME type for JPG's (image/jpeg not image/jpg)

Beta 2

New features

  1. Added the ability to control generated image quality (see CONFIG, $jpg_quality)

  2. Added configurable resolution breakpoints (see CONFIG, $resolutions)

  3. Optional Cache checking - defaults to on (see CONFIG, $watch_cache)

Bug Fixes

  1. The PHP now checks that the GD extension is loaded before proceeding

  2. Clarified PHP comments further

Beta 1

New features

  1. Initial public release

  2. Commented the PHP for public consumption

  3. Added user-configurable cache directory (see CONFIG, $cache_path)

Bug fixes

  1. Didn't generate downscaled images due to typo