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.
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.
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.
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.
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.
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.
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
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.
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.)
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.
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.)
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.
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.
Here's the HOWTO for RMagick 1. Here's the HOWTO for RMagick 2. Don't know which version you need? Look here.
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.
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
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
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:
tarcompletes 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
configurescript. If the files have the wrong information, ImageMagick/GraphicsMagick won't be able to use the fonts on your system.
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:
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
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.
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.
|libfreetype.so||FreeType (TrueType fonts)|
|libgs.so||Ghostscript (see the ImageMagick/GraphicsMagick README.txt file)|
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:
To specify an include file directory, define the CPPFLAGS environment variable to the necessary gcc "-Idirectory" option. For example,
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.
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
/usr/local/lib directory. However, the Linux
dynamic linker/loader only looks for shared objects in
/usr/lib by default. You have
/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:
ld.so(8) for more information about
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.
Upgrade to the latest release of RubyGems:
gem update --system
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:
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.