CPAN, the Comprehensive Perl Archive Network is a free community provided library of Perl programs.

Installing CPAN

Here are instructions for upgrading 64-bit CPAN, tested April 2014 on 10.9.2 Mavericks,
July 2015 on 10.10.4 Yosemite,
May 2016 on 10.11.5 El Capitan,
July 2016 on 10.12.6 Sierra.
March 2018 on 10.13.3 High Sierra,
January 2019 on Mojave.


Interaction with MacPorts on Sierra and El Capitan

If I install modules from Macports, it will install Perl 5.26.2 (as of 06/09/18), newer than the system-provided 5.18, into /opt/local/bin/perl. Before installing CPAN modules, you need to change your startup environment to point to the new Perl.

    export PERL5LIB=/Users/thvv/bin:/opt/local/lib/perl5/5.26
    export PERL_LOCAL_LIB_ROOT="/opt/local/lib/perl5/5.26"
    export PERL_MB_OPT="--install_base "/opt/local/lib/perl5/5.26""
    export PERL_MM_OPT="INSTALL_BASE=/opt/local/lib/perl5/5.26"

Then I need to make the Perl programs and modules in my ~/bin that begin with the "shebang" line #!/usr/bin/perl find the new version of Perl. I used to replace /usr/bin/perl with a link to /opt/local/bin/perl, but as of macOS Sierra, /usr/bin is prevented from change by System Integrity Protection (SIP). The best thing to do is to change all the shebang lines for Perl programs in my library to #!/usr/local/bin/perl, and then create a symlink from /usr/local/bin/perl to /opt/local/bin/perl. (The alternative is to disable SIP by booting into Recovery, reboot and fix /usr/bin/perl, reboot into Recovery again to enable SIP, and reboot again.)

When Apple releases an update to the OS, check to make sure that /usr/local/bin/perl is still a link into /opt.

The advantage to this approach is that the Unix systems I use have (or can have) /usr/local/bin/perl set correctly.

Install Process

Make sure you have Xcode installed. (It is free from Apple.) It is no longer sufficient to just do xcode-select. You need the real Xcode to find the right libraries and header files.

After checking my environment, I did sudo -H cpan. CPAN started and asked if I wanted it to set as many default options as possible. I said yes, and it appeared to work. Then CPAN asked if it should choose the best mirror sites for me. Say NO and set them yourself.. Executing r worked, and showed many modules out of date.

I was then able to install modules from the command line. I did install CPAN and reload cpan to upgrade CPAN to the latest version, and this worked.

Next I tried install LWP and this failed with the message "Can't locate object method 'requirements_for_module'". This was a symptom of not setting PERL5LIB. I fixed that and things worked... see below.

To install DBD::mysql, first start the MySQL server. If you have already set the root password for MySQL, do o conf makepl_arg "--testuser=root --testpass=xxxxxxxx", before doing install DBD::mysql and o conf makepl_arg "" afterward.

Installing on Mojave

Macports installed Perl 5.26, newer than the system-provided 5.18. Later installs brought in Perl 5.28 but the library link is to 5.26. I ensured that /usr/local/bin/perl linked to /opt/local/bin/perl. I encountered some problems with individual modules.

Installing DBD::mysql, I got the error dyld: Library not loaded: @rpath/libmysqlclient.21.dylib. I tried sudo install_name_tool -id /usr/local/mysql-8.0.14-macos10.14-x86_64/lib/libmysqlclient.21.dylib /usr/local/mysql-8.0.14-macos10.14-x86_64/lib/libmysqlclient.21.dylib to fix this and got further with cpan.

Then I got the errors dyld: Library not loaded: libssl.1.0.0.dylib and dyld: Library not loaded: libcrypto.1.0.0.dylib. These libraries are loaded in /opt/local/lib. So I tried sudo ln -s /opt/local/lib/libcrypto.1.0.0.dylib /usr/local/lib/libcrypto.1.0.0.dylib and sudo ln -s /opt/local/lib/libssl.1.0.0.dylib /usr/local/lib/libssl.1.0.0.dylib and it worked. Perhaps instead of using install_name_tool I could have just done sudo ln -s /usr/local/mysql-8.0.14-macos10.14-x86_64/lib/libmysqlclient.21.dylib /usr/local/lib/libmysqlclient.21.dylib.

Before you install MaxMind::DB::Reader::XS, you must download and install libmaxxminddb from Then you need to copy /usr/local/include/maxminddb.h and /usr/local/include/maxminddb_config.h into /opt/local/include/ before installing the module, if your Perl was installed by MacPorts as mine was. (People using Homebrew don't have this problem.)

Installing on High Sierra and Sierra

Macports installed Perl 5.24, newer than the system-provided 5.18. Later installs have upgraded it to 5.26.2.

(Gotcha) Perl 5.22 and later emit complaints about some regular expressions that 5.18 accepted happily. I had to change /{{..../ to /\{\{..../ to put a backslash in front of open braces. This is backward compatible.

Installing on El Capitan

(Another gotcha) CPAN on El Capitan failed installing DBD::mysql with the message

  # Failed test 'dbh insert id 0 == max(id) 2 in dbd_mysql_t31'
  # at t/31insertid.t line 58.
  # got: 0
  # expected: 2
  # Looks like you failed 1 test of 18.

I had to do force install DBD::mysql and that seemed to work.

Installing on Yosemite

Installing OSX 10.10.5 broke my Perl setup. I had set PERL5LIB to $HOME/bin:/opt/local/lib/perl5/site_perl/5.16.3, but 10.10.5 installed Perl 5.18 as the system Perl. Access to MySQL from Perl started failing, saying that the 5.16 library was incompatible with the 5.18 Perl loader. I set PERL5LIB to $HOME/bin:/Library/Perl/5.18/, trying to avoid using the MacPorts Perl, and made a symlink to the new system Perl in my /bin directory with ln -s /usr/local/bin/perl. Then I did sudo -H /usr/bin/cpan to install a bunch of stuff into the system Perl lib, such as DBI. CPAN still failed installing DBD::mysql, even after setting the CPAN config using o conf makepl_arg "--testuser=aaa --testpass=bbb". I searched the Web, which suggested sudo ln -s /usr/local/mysql/lib/libmysqlclient.18.dylib /usr/local/lib/libmysqlclient.18.dylib and this allowed me to install DBD::mysql and run Perl MySQL database accesses. (This problem did not occur on later releases.)

Installing on OSX Snow Leopard and Mavericks

When I executed install DBD::mysql on Snow Leopard, the install failed, saying it could not find libmysqlclient.18.dylib. (This problem did not occur on Mountain Lion, but it did on Mavericks.) I Googled and found . It suggested

 sudo install_name_tool -id /usr/local/mysql/lib/libmysqlclient.18.dylib\

I did this and re-tried install DBD::mysql, and it succeeded. This problem did not occur on Yosemite and El Capitan.

Home | FAQ © 2010-2019, Tom Van Vleck updated 2019-01-31 17:18