CPAN, the Comprehensive Perl Archive Network is a free community provided library of Perl programs. My program expandfile, which I use to generate web pages, uses CPAN modules.

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 10.14.


Interaction with Perl from MacPorts

If I install modules from Macports, macports will require and install Perl 5.26.2 (dated 06/09/18) into /opt/local/bin/perl. (This is much newer than the (2013) version 5.18 of Perl provided by Apple.) 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 my 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 use sudo to 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. You have to check this after every Apple OS update.)

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 my Perl library code can also be ported to Unix systems.

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 Apple-provided 5.18. I ensured that /usr/local/bin/perl linked to /opt/local/bin/perl and that PER5LIB referenced /Users/thvv/bin:/opt/local/lib/perl5/5.26. (Later installs brought in Perl 5.28.)

I encountered some problems with individual modules.

Make sure you have the right version of Xcode installed, or modules will not build. I didn't understand that when I was offered Xcode 11.1 for macOS 10.15 Catalina, that installing it would prevent building for macOS 10.14 Mojave. This mistake also prevented the compilation of libmaxminddb. I had to reinstall the old Xcode.

Before you install MaxMind::DB::Reader::XS, you must download and install libmaxminddb 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.

Trying to install GeoIP2::Database::Reader failed when it tried to install the prerequisite NetAddr::IP and got a mysterious error 255. cpan suggested using the 'reports' command to fetch test results, but that failed with error 500. Finally I did a force install, since the errors were in IPV6 addresses, which I am not using.

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.

I tried this same sequence of installs about 8 months later. Everything seemed to work up until DBD::mysql. It got the same error message and I tried the symlinks above. But libssl.1.0.0.dylib and libssl.1.0.0.dylib were not installed in /usr/local/lib/. Instead I had libssl.1.1.dylib and libssl.1.1.dylib in /usr/local/lib/. In other words, macports had installed a newer version of libcrypto and libssl than DBD::mysql wanted. So, with no other ideas, I did sudo ln -s /opt/local/lib/libcrypto.1.1.dylib /usr/local/lib/libcrypto.1.0.0.dylib and sudo ln -s /opt/local/lib/libssl.1.1.dylib /usr/local/lib/libssl.1.0.0.dylib and the install completed. It has worked so far ... but I don't do any ssl or crypto operations in mysql.

I am not looking forward to dealing with these problems for Catalina.

Installing on High Sierra and Sierra

Macports installed Perl 5.24, newer than the Apple-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.

Installing on Linux

I upgraded a Ubuntu server to 16.04 Xenial. My CPAN modules were not there after the upgrade. So I installed them using the same process. But DBD::mysql failed to install, with the message

  could not install CPAN module DBD::mysql

  Configuring D/DV/DVEEDEN/DBD-mysql-4.050.tar.gz with Makefile.PL
  Can't exec "mysql_config": No such file or directory at Makefile.PL line 89.

I searched Google for the answer and found several wrong answers, and then the solution. The mysql_config command wasn't installed. I had to do

  sudo apt-get install libdbd-mysql-perl
  sudo apt-get install libmysqlclient-dev

I did this and re-tried install DBD::mysql, and it succeeded.

On Fedora 31 Linux, install both mysql-community-server and community-mysql-devel before installing DBD::mysql, in order to get mysql_config.

On Fedora 31 Linux, installing NET::DNS fails with errors about a missing system include file. Still researching.

Home | FAQ © 2010-2021, Tom Van Vleck updated 2021-04-24 10:50