RMagick Installation FAQ
Original Image

Read Me First!

RMagick can be more difficult to install than the typical Ruby extension. First you have to install ImageMagick or GraphicsMagick, and those libraries require a lot of other libraries. Nevertheless, the process can be made easier with a bit of planning. On this page I'll try to answer the most common questions about installing RMagick. Give it a quick scan before you start downloading files.

(If you encounter problems that aren't covered here, or find a mistake in what I've written, let me know.)

Go back to the home page.

Index to Questions

  1. What operating systems can I install RMagick on?
  2. Does RMagick have to be compiled with a C compiler?
  3. What prerequisites does RMagick have?
  4. What prerequisites does ImageMagick/GraphicsMagick have?
  5. What RMagick package should I download?
  6. What about a third-party package such as an .rpm?
  7. How do I install RMagick on Microsoft Windows?
  8. I've got a version of ImageMagick for Windows that is more recent than the bundled version. Can I use it?
  9. How do I install RMagick on OS X?
  10. How do I install RMagick on Linux, FreeBSD, or other *nix-like system?
  11. Help! Too many examples failed. What do I do?
  12. Help! I'm getting the message "No decode delegate for this image format." What does that mean?
  13. Help! I'm getting the message "unable to read font `(null)'." What should I do?
  14. Help! I'm getting the message "Can't find libMagick, libMagickCore, or one of the dependent libraries." What should I do?
  15. Help! I'm getting the message "libMagickWand.so.1: cannot open shared object file: No such file or directory" I know ImageMagick is installed! What should I do? What should I do?
  16. Help! I'm getting the message "Error installing gem rmagick[.gem]: buffer error". What should I do?
  17. Help! I'm getting the message "unable to open X server `'." or "display: unable to open X server `:0.0'". How can I fix that?

What operating systems can I install RMagick on?

RMagick runs on Linux, FreeBSD, OS X, and *nix-like systems such as Solaris and Cygwin. You can also use RMagick on Microsoft Windows 2000, XP, and Vista.

Does RMagick have to be compiled with a C compiler?

It depends.

What prerequisites does RMagick have?

Ruby

You need to have Ruby 1.8.x. You can get by with version 1.6.7 or 1.6.8 if you don't need to use RVG. If you want to use RMagick with Ruby 1.9.0 you must install RMagick 2.

If you're installing on Microsoft Windows you do not have to read any more of this information. Skip to this question.

Developer's tools

Unless you install RMagick from a pre-compiled binary package for your particular system, you must be able to compile and link its source code. This is necessary even when you use the RMagick gem file to install RMagick. You'll need to have the standard set of developer's tools. On most systems these tools include gcc, make, and the GNU binutils. Typically each distribution has its own packages for these tools. If you do not have these tools installed consult your system's documentation. On OS X these tools are part of the Xcode Tools. See here for more information about installing RMagick on OS X.

Ruby header files

You'll need to have the Ruby header files (ruby.h, etc.) installed. If you installed Ruby by compiling the source code you already have the header files. If Ruby was pre-installed on your system, or you installed Ruby from a pre-compiled package, you may need to install the Ruby header files separately.

ImageMagick or GraphicsMagick

You also need one or the other of ImageMagick or GraphicsMagick. GraphicsMagick is a friendly fork of ImageMagick. You only need one of these. Which one you choose is up to you. If you use ImageMagick you must use version 6.0.0 or later. If you want to install RMagick 2 you must use ImageMagick 6.3.0 or later. You can use any version of GraphicsMagick. Both these libraries have a significant number of prerequisites. See the next question.

What prerequisites does ImageMagick/GraphicsMagick have?

Support for GIF is built in to ImageMagick and GraphicsMagick, but they rely on delegate libraries to support most of the other image file formats. To build the example images for the RMagick HTML documentation, you'll need to install the libraries for these image formats:

You may also want to install

These libraries are usually available as binary installs (.deb, .rpm, etc.). Otherwise, most of the delegate libraries are available as source tarballs from http://www.imagemagick.org/pub/delegates/ and from their respective web sites.

You must also have an X server installed to use the display and animate methods. For *nix-ish systems this is already installed. For Cygwin, check here. For OS X, you'll need X11, the X11SDK, and the Xcode tools from the OS X installation disk. For Microsoft Windows, you're out of luck.

The above lists are neither complete nor authoritative and are subject to change. See the README.txt file that accompanies ImageMagick/GraphicsMagick for more information.

What RMagick package should I download?

That depends on what operating system you're using. If you're installing on Linux, FreeBSD, OS X, the Cygwin environment on MS Windows, or another *nix-like system, you have two choices. If you're a fan of RubyGems you can use the RMagick gem. Or you can download the source tarball from the RMagick project page on RubyForge.

If you're installing on Microsoft Windows you should download the rmagick-win32 gem from RMagick's project page on RubyForge. This gem file is bundled with the ImageMagick Windows installer. (See this question for more info about the rmagick-win32 gem.)

What about a third-party package such as an .rpm?

I am not familiar with any of the third-party RMagick packages that are available for various Linux and *BSD distributions, so I can't offer any advice. If you want to try installing RMagick using one of these packages be my guest but if you have problems please contact the packager, not me.

Although I've never used it, if you're planning on developing Rails applications on OS X, then the Locomotive package is getting a lot of good buzz. There's a version of Locomotive that includes ImageMagick and RMagick.

How do I install RMagick on Microsoft Windows?

Use the rmagick-win32 gem. This gem is bundled with a a copy of the ImageMagick Windows installer so you don't need to download your own copy. Download the rmagick-win32 gem from the RMagick project page on RubyForge, unzip it into a temporary directory, and follow the instructions in the README.html file you'll find in the package. (This gem is not for use with the Cygwin environment for Windows. See this question.)

I've got a version of ImageMagick for Windows that is more recent than the bundled version. Can I use it?

No. You must use the ImageMagick Windows installer that is bundled with RMagick even if a later version is available from ImageMagick. RMagick will not run if you try to use a different version. Here is more information about the ImageMagick Windows installer.

How do I install RMagick on OS X?

You have two choices, a procedure that uses MacPorts and a procedure that does not use MacPorts. Each has advantages and disadvantages.

The procedure that uses MacPorts is easier to maintain because you can just use MacPorts and RubyGems to stay current. However the ImageMagick port may be out-of-date (although it's usually very current).

The procedure that does not use MacPorts is not really designed for maintenance. The only way to upgrade is to reinstall everything. However, some people prefer not to use MacPorts. It's up to you.

  1. If you want to use MacPorts:  Here is an OS X installation HOWTO that explains how to use MacPorts to install the delegate libraries and ImageMagick and use RubyGems to install RMagick. You must install the XCode Tools, the X11 SDK, and X11.app and be familiar with Terminal.app.
  2. If you don't want to use MacPorts:  Jon Maddux maintains an excellent installer for ImageMagick for Mac OS 10.5 and 10.6. Once you install ImageMagick, follow the standard instructions for installing RMagick on Unix, starting at step 3. This script assumes that you have already installed, or are prepared to install, the Xcode Tools.

How do I install RMagick on Linux, FreeBSD, or other *nix-like system?

Here's the HOWTO for RMagick 1. Here's the HOWTO for RMagick 2. Don't know which version you need? Look here.

Help! Too many examples failed. What do I do?

As part of the installation process, the installer runs over 175 example scripts. These scripts serve two purposes. First, the scripts and the images they generate are used in the HTML documentation. Second, the scripts validate your installation and make sure that you have everything you need to use RMagick. When 5 or more examples fail, the installer determines that something is wrong and issues this message.

Look at the error messages issued by the failing examples. Usually the message will be one of the messages listed below. Refer to the help for that message to resolve your problem. If the message is not one of those listed below, first read the install HOWTO for your specific O/S (Windows, OS X, Linux and *BSD) and ensure that you've installed everything according to the instructions.

If you installed ImageMagick or GraphicsMagick or RMagick using a prebuilt package such as a .deb, .rpm, or .port, refer to the the installation instructions for that package. You might also try a web search engine such as Google. Searching for "RMagick install myosname" will often lead to web pages with advice about installing RMagick using your particular O/S's packaging system. (Yes, I know that sounds obvious but a lot of people don't think about doing it.)

Finally, if you still have problems, you can ask for help on the RMagick Help Forum or send email to rmagick AT rubyforge DOT org.

Help! I'm getting the message "No decode delegate for this image format." What does that mean?"

It means that ImageMagick/GraphicsMagick isn't configured to use a delegate library for that image format. If you're getting this message from one or more of the RMagick example scripts, then you didn't install one of the required delegate libraries, or it's installed in a directory where ImageMagick/GraphicsMagick couldn't find it. You can use the image's file extension to determine which library is missing (.jpg -> libjpeg, .tif -> libtiff, etc.) Install the library and re-run ImageMagick/GraphicsMagick's ./configure script. Check the configuration summary to make sure that ImageMagick/GraphicsMagick is properly configured. If so, re-run make and make install. You may have to re-install RMagick, too.

You can find out how ImageMagick is configured, including delegate configuration, by entering this command:

convert -list configure

Help! I'm getting the message "unable to read font `(null)'." What should I do?

It means that ImageMagick/GraphicsMagick isn't configured with support for reading fonts or can't find any fonts to read. The most common reasons for this message are:

You don't have any fonts installed.
This can't occur on MS Windows if you used the rmagick-win32 gem because the gem takes care of font configuration. It is very rare on Linux, FreeBSD, and Solaris because typically these systems have PostScript fonts installed by default. However, on OS X no PostScript fonts are installed by default. If you use this procedure to install RMagick on OS X the standard Ghostscript fonts are installed when you install the Ghostscript package from MacPorts. If you want to install the fonts separately, download this file ftp://ftp.imagemagick.org/pub/ImageMagick/delegates/ghostscript-fonts-std-8.11.tar.gz. and use the tar command to copy them into /usr/local/share. After tar completes you can erase the ghostscript-fonts-std-8.11.tar.gz file. You may still need to reconfigure ImageMagick to recognize the fonts.
sudo tar xzf ghostscript-fonts-std-8.11.tar.gz -C /usr/local/share
ImageMagick/GraphicsMagick isn't configured to use FreeType or Ghostscript.
FreeType and Ghostscript are prerequisites for ImageMagick/GraphicsMagick and RMagick. ImageMagick/GraphicsMagick prefers to use FreeType but will fall back to Ghostscript if FreeType is not available. See this question for a complete list of prerequisite libraries.
The font configuration file is wrong.
ImageMagick/GraphicsMagick rely on one or more font configuration files for font management. These files are created by the configure script. If the files have the wrong information, ImageMagick/GraphicsMagick won't be able to use the fonts on your system.

Diagnosing the problem

First, remember that RMagick relies entirely on ImageMagick/GraphicsMagick for font management. Therefore the problem lies with the configuration of ImageMagick/GraphicsMagick. To see how ImageMagick/GraphicsMagick is configured for fonts, type:

convert -list font

This command will show you the fonts that ImageMagick/GraphicsMagick is configured to use. Note that the list may include some fonts that aren't installed on your system, and may not include every font installed on your system!. Look for the lines that start with "Path:". There will be one for each font configuration file. (Typically there is a font configuration file for PostScript fonts and one for TrueType fonts.) The line looks like this:

Path: /usr/lib/ImageMagick-6.2.5/type-ghostscript.mgk

Open the file(s) in a text editor. For each font there is an entry like this:

<type
    name="AvantGarde-Book"
    fullname="AvantGarde Book"
    family="AvantGarde"
    foundry="URW"
    weight="400"
    style="normal"
    stretch="normal"
    format="type1"
    metrics="/usr/share/fonts/default/Type1/a010013l.afm"
    glyphs="/usr/share/fonts/default/Type1/a010013l.pfb"
    />

Ensure that the files listed in the metrics and glyphs attributes are actually present. If the font files are actually on your system but in different directories, you can hand-edit the file to correct the attributes. If you're not comfortable hand-editing the files, re-run ImageMagick's/GraphicsMagick's configure script and specify the correct path to the --with-gs-font-dir option (and optionally the --with-windows-font-dir option). See ImageMagick's/GraphicsMagick's README.txt file for more information about these options.

If the font files are not present, install them. How you do this varies depending on your system. If you're using OS X, see the instructions above for downloading and installing ghostscript-fonts-std-8.11. If you're using Linux, Cygwin, or another *nix variant, typically the standard PostScript fonts are available as a package, or you can install ghostscript-fonts-std-8.11 as describe for OS X.

If that doesn't solve the problem, sometimes ImageMagick/GraphicsMagick will tell you what the problem is. Enter this command:

convert label:abcdef test.gif

If you get the message

convert: FreeType library is not available 'abcdef'.

install the FreeType library and re-install ImageMagick/GraphicsMagick.

Help! I'm getting the message "Can't find libMagick, libMagickCore, or one of the dependent libraries." What should I do?

Usually this problem occurs when installing RMagick from source over a version of ImageMagick/GraphicsMagick from a binary package such as an .rpm or .deb. The problem occurs because the package installs just ImageMagick/GraphicsMagick but omits one (or all) of the libraries that it uses, such as the FreeType library or the XML parsing library. Or the libraries are installed but not the header files that RMagick needs. Also, some Linux distributions (such as Ubuntu) distribute an package file for ImageMagick that contains only the ImageMagick commands, but not the library itself. This is confusing because the ImageMagick utilities work but you still can't install RMagick.

If you find yourself getting the "Can't find libMagick, libMagickCore, or one of the dependent libraries" message it is possible to find out what library the installer script is complaining about. Given that information you can install the library (and any developers packages that accompany the library) and try the RMagick install again.

The mkmf.log file usually contains everything you need to know to diagnose RMagick installation problems. The tricky part is interpreting what you find there. Go to the RMagick install directory and look for a file in the ext/RMagick directory named "mkmf.log". Open this file in a text editor. Search for the line that says "checking for InitializeMagick() in -lMagick...". Following this line you'll see a gcc command. Following the gcc command you'll see gcc's error message. This error message describes why gcc failed and should give you a hint about what went wrong. Here's an example, from GNU ld version 2.18:

/usr/bin/ld: warning: libjpeg.so.62, needed by
/home/software/ImageMagick-6.3.9/lib/libMagickWand.so, not found

A message like that means that a dependent library is missing. With this information you can figure out what is missing from your system.

This table shows the names of the most common dependent library files in the left column. The right column identifies the dependency that the file belongs to.

File name Dependency
libjpeg.so JPEG
liblcms.so LCMS
libbz2.so BZLIB
libpng.so PNG
libtiff.so TIFF
libfreetype.so FreeType (TrueType fonts)
libwmf.so WMF
libwmflite.so
libSM.so X11
libICE.so
libX11.so
libXext.so
libxml2.so XML
libz.so ZLIB
libgs.so Ghostscript (see the ImageMagick/GraphicsMagick README.txt file)
libexif.so EXIF
libfpx.so FlashPIX

Using the table above, determine which dependency is missing, install it and try again. I recommend installing the dependent libraries from binary packages if they are available for your system.

If you know for a fact that a dependent library that gcc can't find is already installed, then it is probably in an different directory than ./configure expects. You need to tell ./configure where it is. (Normally the RMagick install gets this information from ImageMagick/GraphicsMagick itself.) You can use the LDFLAGS and CPPFLAGS environment variables to add directories to ./configure's search paths.

To specify a additional directory to search for libraries, define the LDFLAGS environment variable to the necessary gcc "-Ldirectory" option. For example, if you installed libfreetype.so in /opt/local/lib, do this:

export LDFLAGS="-L/opt/local/lib"

To specify an include file directory, define the CPPFLAGS environment variable to the necessary gcc "-Idirectory" option. For example,

export CPPFLAGS="-I/opt/local/include"

You can specify multiple directories by separating the options with a space.

You can get more information about installing ImageMagick here, and about installing GraphicsMagick here.

Help! I'm getting the message "libMagickWand.so.1: cannot open shared object file: No such file or directory" I know ImageMagick is installed! What should I do?

The full text of the message is:

/usr/lib/ruby/gems/1.8/gems/rmagick-2.2.2/lib/RMagick2.so:
libMagickWand.so.1: cannot open shared object file: No such file or
directory - /usr/lib/ruby/gems/1.8/gems/rmagick-2.2.2/lib/RMagick2.so
(LoadError)

The message will be slightly different if you are installing RMagick from source or you've installed GraphicsMagick.

This message is extremely confusing. It looks like Ruby is complaining that it can't find RMagick.so, but actually Ruby is complaining that it can't find libMagickWand.so.

Unless you specify a different directory when you run the configure script, the ImageMagick/GraphicsMagick shared object file (libMagickWand.so or libGraphicsMagick.so) is installed in the /usr/local/lib directory. However, the Linux dynamic linker/loader only looks for shared objects in /lib and /usr/lib by default. You have to add /usr/local/lib to the list of locations it searches. The easiest way to do this is to use the LD_LIBRARY_PATH environment variable. Add this statement to one of your start-up files:

export LD_LIBRARY_PATH=/usr/local/lib

See ld.so(8) for more information about LD_LIBRARY_PATH.

If you have root authorization on your system you can also add /usr/local/lib to the linker/loader's cache. See ldconfig(8) for more information.

Help! I'm getting the message "Error installing gem rmagick[.gem]: buffer error". What should I do?

Upgrade to the latest release of RubyGems:

gem update --system

Help! I'm getting the message "unable to open X server ''." or "display: unable to open X server ':0.0'". How can I fix that?

This message usually occurs on OS X, the first time try to use RMagick to display an image after installing X11. ImageMagick and GraphicsMagick use X11 to display images. This is a message from ×Magick saying that it doesn't know where to display the image. The answer is, of course, "on the display," but we've got to say it in a way that X11 understands.

First, make sure X11 is actually running. If not, start it by double-clicking /Applications/Utilities/X11. X11 must be running to use RMagick to display an image. You may want to add X11 to the list of login items for your account. Each time X11 starts, it also opens an xterm window. Xterm is X11's default terminal application. You can always close this window. You won't need it for anything.

Once X11 is running, you must tell it which display to use. This is done with the DISPLAY environmental variable. Start the Terminal application and enter this command:

export DISPLAY=:0.0

At this point should should be able to use RMagick to display images. To ensure that the DISPLAY variable is always set properly, add this command to your .profile.