View on GitHub


Read/write access to PNG images in pure Ruby.

ChunkyPNG a pure Ruby library that can read and write PNG files. It aims to be able to read any image conforms to, the PNG standard, give read/write access to the image’s pixels and metadata, and efficiently encode images.

The name of this library is intentionally similar to Chunky Bacon and Chunky GIF. Use Google if you want to know _why. :-)

Basic usage

Install the library using [sudo] gem install chunky_png.

This screencast by John Davison shows how to create an image using basic operations in ChunkyPNG. The follow Ruby snippet will also give you an overview on how to use the library.

require 'chunky_png'

# Creating an image from scratch, save as an interlaced PNG
png =, 16, ChunkyPNG::Color::TRANSPARENT)
png[1,1] = ChunkyPNG::Color.rgba(10, 20, 30, 128)
png[2,1] = ChunkyPNG::Color('black @ 0.5')'filename.png', :interlace => true)

# Compose images using alpha blending.
avatar = ChunkyPNG::Image.from_file('avatar.png')
badge  = ChunkyPNG::Image.from_file('no_ie_badge.png')
avatar.compose!(badge, 10, 10)'composited.png', :fast_rgba) # Force the fast saving routine.

# Accessing metadata
image = ChunkyPNG::Image.from_file('with_metadata.png')
puts image.metadata['Title']
image.metadata['Author'] = 'Willem van Bergen''with_metadata.png') # Overwrite file

# Low level access to PNG chunks
png_stream = ChunkyPNG::Datastream.from_file('filename.png')
png_stream.each_chunk { |chunk| p chunk.type }

For more information on the API, see the project’s RDoc documentation


Notes and caveats

Performance: ChunkyPNG keeps memory usage and speed in mind. As it is a pure Ruby library, it will not be able to match the performance of a native library. To partially overcome this issue, OilyPNG implements some of the ChunkyPNG algorithms in C, which provides a massive speed boost to encoding and decoding and some other operations, without any API changes.

Security: ChunkyPNG is vulnerable to decompression bombs, which means that ChunkyPNG is vulnerable to DOS attacks by running out of memory when loading a specifically crafted PNG file. Because of the pure-Ruby nature of the library it is very hard to fix this problem in the library itself.

In order to safely deal with untrusted images, you should make sure to do the image processing using ChunkyPNG in a separate process, e.g. by using fork or a background processing library.


The library was written by Willem van Bergen for