Hello. My name is Noemi Millman, and Triopter is my web development agency. We handcraft beautiful, dynamic websites.

See what I can do for you.

Noemi Millman: Triopter: How to Install Perl Modules on Mac OS X in 4 Easy Steps

How to Install Perl Modules on Mac OS X in 4 Easy Steps

Today at work, I learned how to install Perl modules using CPAN. It’s a lot easier than I thought.

You see, for the past couple of years, I’ve been a bit frustrated because OS X does not come with a whole lot of Perl modules pre-installed, and for all I googled, I couldn’t find an “idiot’s” guide for moderately-savvy-but-not-expert users like myself to install modules and dependencies on demand.

The only instructions I could find point to Fink, which basically installs modules in a path that isn’t included in the Perl @INC variable, meaning you have to manually specify the full path to the modules in every script — which is not a lot of fun if you’re developing on OS X and deploying on Red Hat, for instance.

Moreover, Fink doesn’t seem to make every module available, and it’s not very easy to determine which Fink package you need to install if you need a particular module.

So, with a script that called on several apparently unavailable modules, and a deadline looming, I finally decided to suck it up and figure out how to use CPAN to install them:

1) Make sure you have the Apple Developer Tools (XCode) installed.

These are on one of your install discs, or available as a huge but free download from the Apple Developer Connection [free registration required] or the Mac App Store. I thought I had them, but apparently when we upgraded that computer to Tiger, they went missing.

If you don’t have this stuff installed, your installation will fail with errors about unavailable commands.

1.5) Install Command Line Tools (Recent XCode versions only)

(Thank you to Tom Marchioro for informing me about this step.)

Older versions of XCode installed the command line tools (which are required to properly install CPAN modules) by default, but apparently newer ones do not. To check whether you have the command line tools already installed, run the following from the Terminal:

$ which make

This command checks the system for the “make” tool. If it spits out something like /usr/bin/make you’re golden and can skip ahead to Step 2. If you just get a new prompt and no output, you’ll need to install the tools:

  1. Launch XCode and bring up the Preferences panel.
  2. Click on the Downloads tab
  3. Click to install the Command Line Tools

If you like, you can run which make again to confirm that everything’s installed correctly.

2) Configure CPAN.

$ sudo perl -MCPAN -e shell

perl> o conf init

This will prompt you for some settings. You can accept the defaults for almost everything (just hit “return”). The two things you must fill in are the path to make (which should be /usr/bin/make or the value returned when you run which make from the command line) and your choice of CPAN mirrors (which you actually choose don’t really matter, but it won’t let you finish until you select at least one). If you use a proxy or a very restrictive firewall, you may have to configure those settings as well.

If you skip Step 2, you may get errors about make being unavailable.

3) Upgrade CPAN

$ sudo perl -MCPAN -e 'install Bundle::CPAN'

Don’t forget the sudo, or it’ll fail with permissions errors, probably when doing something relatively unimportant like installing man files.

This will spend a long time downloading, testing, and compiling various files and dependencies. Bear with it. It will prompt you a few times about dependencies. You probably want to enter “yes”. I agreed to everything it asked me, and everything turned out fine. YMMV of course. If everything installs properly, it’ll give you an “OK” at the end.

4) Install your modules. For each module….

$ sudo perl -MCPAN -e 'install Bundle::Name'


$ sudo perl -MCPAN -e 'install Module::Name'

This will install the module and its dependencies. Nice, eh? Again, don’t forget the sudo.

The first time you run this after upgrading CPAN, it may prompt you to configure again (see Step 2). If you accept its offer to try to configure itself automatically, it may just run through everything without a problem.

There are a couple of potential pitfalls with specific modules (such as the LWP::UserAgent / HEAD issue), but most have workarounds, and I haven’t run into anything that wasn’t easily recoverable.

And that’s it!

Did you find this useful? Is there anything I missed?

  1. COMMENT: by Ken, January 15th, 2008

    thank you!

    similarly, i bet it would be also helpful for some people to see how to install perl packages with FC8 using yum…say you want to install the Perl Frontier::Client package (and its dependencies)…

    $ su root

    # yum -y install perl-Frontier-RPC

    …all you do is append a ‘perl-’ to the package name and substitute the ‘::’ for a ‘-’ and you should be all set…

  2. COMMENT: by Alex, March 14th, 2008

    This gave me the courage to get to grips with CPAN ;-) Very helpful, thanks!

  3. COMMENT: by jpd, March 14th, 2008

    Thanks. On Leopard there were some diffs but nothing too bad…The only thing I would say for newbies is that you don’t type sudo perl -MCPAN -e ‘install Module::Name’ – Module & Name are different depending what module you are loading. If you want the LWP module for web manipulation use sudo perl -MCPAN -e ‘install Bundle::lwp’

    Hope that helps

  4. COMMENT: by Noemi Millman, March 16th, 2008

    Thanks, jpd. Would you mind sharing the differences you encountered on Leopard?

  5. COMMENT: by Albert, March 18th, 2008

    Excellent information. I have just got it working on Leopard. Cheers, Albert

  6. COMMENT: by Michele, July 7th, 2008

    Very helpful. I installed on Leopard without too much trouble. Only problem I ran into is that some of the standard config’d locations is not where my programs were located, and didn’t really feel like doing a system-wide grep. Google helped me locate them, and the install went great after that.

  7. COMMENT: by Phoenix2Life, September 26th, 2008

    Extremely well written and perfectly working CPAN guide I have come across. It has since long I always used to download RPMs/TAR.GZs and used to install/configure Perl on my linux boxes. This tutorial has helped me to setup nice automated way which I have been looking for. Thanks.

  8. COMMENT: by nobighair, January 14th, 2009

    Thanks for these instructions, certainly got me up and running.

    I had a list of modules to install. Plus there were a couple I needed to force install. So I found it easier to split it up:

    > sudo perl -MCPAN -eshell

    To get the CPAN shell. Then in the shell:

    > install XML::Writer


    > force install XML::Writer


  9. COMMENT: by Guizard Sébastien, May 5th, 2009


    I had stop the process at the step 2 when you have to enter the adress of the miror cpan(for searching this adress).
    Now, when I restart the command, it don’t ask me for the Cpan miror and the command make was not created. What can I do ? It’s my first macbook, I’ve bought it 3 day ago. I don’t know what can I do ! i’m thinking to re instal Mac OS X. I don’t it’s good idea ! if you can help me I will be very glad ! ! !

    PS : I’m sory if my english is not very good, I’m learning right now in USA ^^

  10. COMMENT: by Noemi Millman, May 6th, 2009

    Guizard, have you tried simply running through Step 2 (above) again?

  11. COMMENT: by Mac, June 20th, 2009

    Now how do you get back to a regular shell to run scripts?

  12. COMMENT: by Noemi Millman, June 23rd, 2009

    Mac: try typing “exit” or “quit”

  13. COMMENT: by Nick, July 30th, 2009

    thank you so much! i needed this

  14. COMMENT: by Simon, November 17th, 2009

    Thanks so much! This is exactly what I was looking for.

  15. COMMENT: by nod, January 4th, 2010

    Thanks muchly! This was very helpful and I’m so glad I came across it. New to Mac and there is a lot to get used to.

  16. COMMENT: by Christian, June 8th, 2010

    I am on 10.6.3

    I followed these instructions and everything went well until I tried to install a module. Maybe I just misread the post, but instead of ‘install Module::Name’ I had to use ‘install Name’

  17. COMMENT: by Noemi Millman, June 8th, 2010

    Christian, you don’t use the word “Module” — it varies depending on what specifically you’re trying to install. See JPD’s notes above.

  18. COMMENT: by Christian, June 8th, 2010

    Right, but if I wanted to install the DateTime module, I would use ‘install DateTime’ and not ‘install Module::DateTime’. That was just unclear to me from the post.

  19. COMMENT: by JM, August 31st, 2010

    Thanks for your tutorial. It was very helpful, and enabled me to just installed seven PERL mods, as well as the Expat C library from Sourceforge.

    Like Christian though, I only had to use “sudo cpan ModuleName” at the Terminal prompt to install most of them. I think there was only one where I had to prefix the command with “Bundle::”.

    This is on a 27″ iMac running Snow Leopard 10.6.4.

    I also installed them on a ten-year-old G4 mini-tower running Tiger.


    Thanks again!

  20. COMMENT: by Pierre, January 10th, 2011

    Nice! Exactly what I needed…using MP3::Tag

  21. COMMENT: by Dan, May 20th, 2011

    Thank you! Very helpful! Worked perfectly.

  22. COMMENT: by Richard Uschold, July 17th, 2011

    So, EXACTLY WERE does CPAN put the perl modules it installs?

    I still get the error: “Can’t locate SOAP/Lite.pm in @INC (…)”

  23. COMMENT: by Richard Uschold, July 17th, 2011

    Never mind! I figured it out. I have two different versions of perl installed. I had to do the CPAN install for both vesions of perl.

    All is good, now!

  24. COMMENT: by Noemi Millman, July 18th, 2011

    Richard, how did you end up with two versions of Perl? Was one installed via Fink or Macports or something?

  25. COMMENT: by bert, November 4th, 2011

    I tried to install LWP and Mechanize but it constantly lead to this when i also try to get the dependencies do you Noemi know what i can do? Regarding CPAN there are few places that have clear explanation as this site. I want to web scrape but it’s damn hard because nobody explains which specific problem i have. I have a mac xcode is installed although i dont know if that means i also have mac developer tools:(

    /usr/bin/make install — NOT OK
    You may have to su to root to install the package
    (Or you may want to run something like
    o conf make_install_make_command ‘sudo make’
    to raise your permissions.Warning (usually harmless): ‘YAML’ not installed, will not store persistent state

  26. COMMENT: by Noemi Millman, November 4th, 2011

    Bert, I’m not an expert in this, but it sounds like one of the dependencies may need to compile and install a binary somewhere on your filesystem that the user you’re logged in as doesn’t have permissions for — possibly when attempting to install a YAML module. You can elevate your permissions using sudo / su but I won’t promise that that’s safe solution. Best of luck!

  27. COMMENT: by bert, November 6th, 2011

    Thanks a lot:) I have nearly figured it all out:P

  28. COMMENT: by Mandy, July 5th, 2012

    Thank you so much! I am relatively new to perl and was having so much trouble installing XML::RSS, and this solved it first time!

  29. COMMENT: by Cliff, July 9th, 2012

    thank you..I finally got this working and the modules installed

  30. COMMENT: by John Wooten, Ph.D., July 10th, 2012

    The instructions don’t appear to work for OS X Lion 10.7.4. I did every step and after a long time of recursively descending down to more and more routines, it fails on almost everything.

    Has anyone installed PDL on OS X Lion 10.7.4? If so, how?

  31. COMMENT: by Tom Marchioro, July 23rd, 2012


    Really clear and useful instructions. You should be proud (and I’m an Eli of an age who doesn’t easily praise a Tiger ;)

    BUT, as John Wooten notes, the instructions need a slight updating for the current state of Appledom. I doubt this is Lion specififc, but the new XCode has turned into a standalone app that does NOT come with the standard command line tools by default, so your instructions should now be:

    1. Make sure you have the Apple Developer Tools Installed.
    2. Launch XCode and bring up the Preferences panel.
    3. Click on the Downloads tab and then click to install the Command Line Tools (otherwise CPAN cannot access a working version of make).

    After that I think Noemi’s instructions work perfectly (at least for DBI and LWP). thanks!

    Hope this helps — tom

  32. COMMENT: by Noemi Millman, July 23rd, 2012

    Thanks, Tom. That’s very good to know, and I’ll update the instructions accordingly.

  33. COMMENT: by laura, July 30th, 2012

    thanks for this! i have one tweak to add if you are trying to do this in Mountain Lion – the install commands all failed for me (at the ftp step) until i added “env FTP_PASSIVE=1″ to the command. so this:

    sudo perl -MCPAN -e ‘install Bundle::Name’

    becomes this:

    sudo env FTP_PASSIVE=1 perl -MCPAN -e ‘install Bundle::Name’

    (tip found at http://hints.macworld.com/article.php?story=20090716132354455)


  34. COMMENT: by Noemi Millman, July 31st, 2012

    Good tip, Laura. It sounds like you may be behind a stricter firewall than most.

  35. COMMENT: by John, August 10th, 2012

    Thanks for this info. Just what was required to fix the problem I was having.

  36. COMMENT: by Anarcissiea, August 24th, 2012

    Worked for me (OS X 10.6.8). Thanks!

  37. COMMENT: by vogen, September 1st, 2012

    Great!! this is what i was looking for. Works with 10.7.4
    Just installed Module Prima

    Thanks heaps

  38. COMMENT: by Avita, November 20th, 2012

    Preciate it man! I was pissed of trying to install modules from cpan on my mac. Thanks a lot for wonderful documentation of the steps.

  39. COMMENT: by Bretfort, January 1st, 2013

    Jazakallah, brief and to the point :)

  40. COMMENT: by Ezmyrelda, March 5th, 2013

    Excellent tutorial! very helpful.

  41. COMMENT: by Collin Dyer, May 13th, 2013

    Thank you very much – worked great for this perl noob!

  42. COMMENT: by Perl on Mac | BnafetS, May 27th, 2013

    [...] to Noemi Millman! Rate this:Share this:Like this:Like [...]

  43. COMMENT: by Gaelle, June 26th, 2013

    Thank you very much : perfectly clear tutorial. I saved an hour thanks to you ;-) Note that CPAN configuration is much simpler now (autoselect mirror for instance)

  44. COMMENT: by Susanne, July 8th, 2013

    Thank you very much for this excellent howto – it certainly saved me a lot of time! Everything worked right away (Mac OS 10.8.3).

  45. COMMENT: by Ryan, July 21st, 2013

    Great article! It helps a lot!

  46. COMMENT: by Jack, November 8th, 2013

    very helpful of CPAN

  47. COMMENT: by Anonymous, December 17th, 2013

    after running the upgrade command (sudo perl -MCPAN -e ‘install Bundle::CPAN’) and starting the long compiling/configuring/testing process, it eventually stopped at

    “t/lock.t …………… 1/4″

    It’s been stuck on that for about 20 minutes now. Is this normal?

  48. COMMENT: by Anonymous, December 17th, 2013

    well I ended up just killing the make test process and it seemed to proceed with the rest of the installation. So far it hasn’t given me any problems. I guess it was just some weird bug

  49. COMMENT: by Flo, June 18th, 2014

    Still relevant for Maverick, thanks a lot!

  50. COMMENT: by Jim, February 20th, 2016

    I am a neophyte to Mac (less than 1 week old) and have successfully followed your instructions for installing CPAN. They worked perfectly. Thanks for the simple and accurate instructions. However, when I try to install a module (sudo perl -MCPAN -e ‘install Tk’) it keeps asking for a password to install it, which I don’t have, and can’t get beyond the lock key symbol that pops up after the prompt ‘Password:’. I recently installed a password protection program (SafeinCloud), which may be related. Any advice?

Post a Comment

Your email is never published nor shared. Required fields are marked *

Comments may be held for moderation to prevent spam: your comment may not appear immediately.