Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


Lua bindings to ImageMagick for LuaJIT using FFI

Subscribe to updates I use magick

Statistics on magick

Number of watchers on Github 271
Number of open issues 21
Average time to close an issue 3 months
Main language MoonScript
Average time to merge a PR 9 days
Open pull requests 10+
Closed pull requests 2+
Last commit over 2 years ago
Repo Created over 7 years ago
Repo Last Updated over 2 years ago
Size 203 KB
Organization / Authorleafo
Page Updated
Do you use magick? Leave a review!
View open issues (21)
View magick activity
View on github
Book a Mock Interview With Me (Silicon Valley Engineering Leader, 100s of interviews conducted)
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating magick for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Build Status

Lua bindings to ImageMagick's MagicWand or GraphicsMagick's Wand for LuaJIT using FFI.


You'll need both LuaJIT (any version) and MagickWand or GraphicsMagickinstalled.

On Ubuntu, to use ImageMagick, you might run:

$ sudo apt-get install luajit
$ sudo apt-get install libmagickwand-dev

You can install GraphicsMagick in place of, or alongside, ImageMagick:

$ sudo apt-get install libgraphicsmagick1-dev

It's recommended to use LuaRocks to install magick.

$ sudo apt-get install luarocks
$ luarocks install magick

Basic Usage

If you just need to resize/crop an image, use the thumb function. It provides a shorthand syntax for common operations.

local magick = require("magick")
magick.thumb("input.png", "100x100", "output.png")

The second argument to thumb is a size string, it can have the following kinds of values:

"500x300"       -- Resize image such that the aspect ratio is kept,
                --  the width does not exceed 500 and the height does
                --  not exceed 300
"500x300!"      -- Resize image to 500 by 300, ignoring aspect ratio
"500x"          -- Resize width to 500 keep aspect ratio
"x300"          -- Resize height to 300 keep aspect ratio
"50%x20%"       -- Resize width to 50% and height to 20% of original
"500x300#"      -- Resize image to 500 by 300, but crop either top
                --  or bottom to keep aspect ratio
"500x300+10+20" -- Crop image to 500 by 300 at position 10,20

If you need more advanced image operations, you'll need to work with the Image object. Read on.


All functions contained in the table returned by require("magick").

thumb(input_fname, size_str, out_fname=nil)

Loads and resizes image. Write output to out_fname if provided, otherwise return image blob. (input_fname can optionally be an instance of Image)


Return a new Image instance, loaded from filename. Returns nil and error message if image could not be loaded.


Loads an image from a Lua string containing the binary image data.

Image object

Calling load_image or load_image_from_blob returns an Image object.

local magick = require "magick"

local img = assert(magick.load_image("hello.png"))

print("width:", img:get_width(), "height:", img:get_height());

img:resize(200, 200)

Images are automatically freed from memory by LuaJIT's garbage collector, but images can take up a lot of space in memory when loaded so it's recommended to call destroy on the image object as soon as possible.

Using GraphicsMagick

ImageMagick and GraphicsMagick implement the same interface. By default the magick module will include ImageMagick. You can specify which library you use by calling require on the module for the appropriate library. At the moment it's impossible to include both libraries into the same process due to collision of function names in the C namespace.

Load ImageMagick directly:

magick = requrie "magick.wand"
local img = magick.load_image("some_image.png")

Load GraphicsMagick directly:

magick = requrie "magick.gmwand"
local img = magick.load_image("some_image.png")

Note: not all methods on Image for ImageMagick are available in GraphicsMagick right now. Pull requests welcome.


Methods mutate the current image when appropriate. Use clone to get an independent copy.

img:resize(w,h, f="Lanczos2", blur=1.0)

Resizes the image, f is resize function, see Filer Types


Resizes the image using adaptive resize

img:crop(w,h, x=0, y=0)

Crops image to w,h where the top left is x, y

img:blur(sigma, radius=0)

Blurs the image with specified paramaters. See Blur Arguments

img:rotate(degrees, r=0, g=0, b)

Rotates the image by specified number of degrees. The image dimensions will enlarge to prevent cropping. The triangles on the corners are filled with the color specified by r, g, b. The color components are specified as floating point numbers from 0 to 1.

img:sharpen(sigma, radius=0)

Sharpens the image with specified parameters. See Sharpening Images


Resizes the image to w,h. The image will be cropped if necessary to maintain its aspect ratio.


Returns Lua string containing the binary data of the image. The blob is formatated the same as the image's current format (eg. PNG, Gif, etc.). Use image:set_format to change the format.


Writes the the image to disk


Gets the width of the image


Gets the height of the image


Gets the current format of image as a file extension like "png" or "bmp". Use image:set_format to change the format.


Sets the format of the image, takes a file extension like "png" or "bmp"


Gets the image compression quality.


Sets the image compression quality.


Gets the image gravity type.


Sets the image's gravity type:

gravity can be one of the values listed in data.moon

img:get_option(magick, key)

Returns all the option names that match the specified pattern associated with a image (e.g img:get_option("webp", "lossless"))

img:set_option(magick, key, value)

Associates one or options with the img (e.g img:set_option("webp", "lossless", "0"))

img:scale(w, h)

Scale the size of an image to the given dimensions.


Coalesces the current image by compositing each frame on the previous frame. This un-optimized animated images to make them suitable for other methods.

img:composite(source, x, y, compose)

Composite another image onto another at the specified offset x, y.

compose can be one of the values listed in data.moon


Strips image of all profiles and comments, useful for removing exif and other data

r,g,b,a = img:get_pixel(x, y)

Get the r,g,b,a color components of a pixel in the image as doubles from 0 to 1


Returns a copy of the image.

img:modulate(brightness=100, saturation=100, hue=100)

Adjust the brightness, saturation, and hue of the image. See Modulate Brightness, Saturation, and Hue


Mutates the image to be a thumbnail. Uses the same size string format described at the top of this README.


Immediately frees the memory associated with the image, it is invalid to use the image after calling this method. It is unecessary to call this method normally as images are tracked by the garbage collector.


Tests use Busted. Install and execute the following command to run tests. You can check the output in spec/output_images/.

$ busted


1.5.0 - Tue Jun 20 13:33:41 PDT 2017

  • Add get_depth and set_depth to GraphicsMagick & ImageMagick

1.4.0 - Tue Jun 6 22:54:12 PDT 2017

  • Add reset_page to GraphicsMagick
  • Add get_format and set_format to GraphicsMagick

1.3.0 - Wed Mar 8 09:49:31 PST 2017

  • Add modulate (@granpc)
  • Add more methods to graphics magick: composite, clone, blur (@granpc)
  • Add reset page to imagemagick wand (@thierrylamarre)
  • Clone method is uses the clone function provided by image magick, garbage collects new image
  • Add thumb method on the image class

1.2.0 - Tue Jul 12 21:10:23 PDT 2016

  • Add preliminary GraphicsMagick support
  • Fix bug with gravity getter/setter (@ram-nadella)
  • Add additional wand method: https://github.com/leafo/magick/pull/32 (@sergeyfedotov)

1.1.0 - Thu Oct 22 05:11:41 UTC 2015

  • add automatic memory management with ffi.gc
  • fix some string memory leaks when getting type and options of image
  • add coalesce, rotate methods to image
  • use pkg-config instead of MagickWand-config to query library
  • all include paths provided by config are searched instead of first


Author: Leaf Corcoran (leafo) (@moonscript)
Email: leafot@gmail.com
Homepage: http://leafo.net

magick open issues Ask a question     (View All Issues)
  • almost 4 years img:colorize() function?
  • almost 5 years expose method for using GetAuthenticPixelQueue
  • almost 5 years bit depth
  • almost 5 years Add `magick.new` and `magick.new_image`
  • almost 5 years Support gif with couple frames
  • about 5 years Sometimes 'line 162 attempt to index a nil value'
  • about 5 years Problem with 2 request
  • almost 7 years Attempt to index a nil value error occured randomly
magick open pull requests (View All Pulls)
  • Use first proper GIF frame for thumbnail
  • Add several functions
  • Add functions: copy image, transform color space, sepia. Const color space
  • Fix gravity getter and setter
  • Adapter imagemagick version 6.9+
  • Create Progressive JPEG.
  • add reset_page()
  • add get and set image profile to image magick
  • Add support for extent method from ImageMagick
  • Fix alpha channel in rotate
magick questions on Stackoverflow (View All Questions)
  • error compiling magick++ header with clang
  • Golang Converting Image magick object to []byte
  • Getting pixel RGB values 0-255 in C++ using Magick++
  • Create a function with return type of image magick object in go lang
  • Create Image magick object from response stream in go lang
  • unable to build magick for golang
  • Add background to the text using Magick++
  • Word-wrapping colored text with magick++
  • Magick++ blur mask
  • Error installing Image Magick on Ubuntu 14.04
  • Is Image Magick 6.2.4 always backwardly compatible with legacy versions?
  • Install Perl Image::Magick on Fedora
  • Image Magick , Add ken burn effect on Gif file
  • How to add word wrapping to texts in Magick++
  • ImageMagick result differ from Magick++
  • ImageMagick compose:args="" to Magick++ API
  • Rails 4 throws image has errors when i use send_data with image magick image
  • How to convert gray scale png image to RGB from comand line using image magick
  • rmagick gem install "Can't find Magick-config"
  • Magick++ - reduce bit-depth of grayscale image
  • Perl module Image::Magick::Q16::constant missing on working Image::Magick?
  • Resize image with Magick++
  • Converting PSD file to JPG using graphic magick
  • How to make white on transparent image using Carrierwave Image magick
  • How to convert a SVG to a PNG with Image Magick?
  • Carrierwave image magick convert png as white transparent for android notification icon
  • Meteor.JS CollectionFS Video to Image Thumbnails (Graphics Magick)
  • Using Magick++ in Qt Creator
  • Identify profile-icc with Image Magick
  • Graphics Magick in NodeJS, using gm package
magick list of languages used
Other projects in MoonScript
Powered by Autocode - Instant Webhooks, Scripts and APIs
Autocode logo wordmark