Common reasons a module won't install

Hi All,

Everyone knows how frustrating it can be to try and fail to install a Perl module. I'm writing an article that will help people troubleshoot the common causes of a module not installing. I've made a list below but have I missed any common installation issues that you've experienced?

  • Unmet Perl dependency (cannot find module in @INC)
  • Unmet C library dependency
  • Perl version not high enough
  • Wrong permissions
  • Broken module
  • Incompatible Operating System
  • Perl not compiled with the right flags
  • Incorrect environment variables

Thanks in advance


By far the most common problem is something broken somewhere in one of the modules on which the module depends.

Incompatibilities between module versions (and sometimes Perl) is usually the cause.

For modules that wrap a command-line program (via e.g. system calls), that program being missing or in an unexpected path can cause problems.

Perl version too high (obvious topical example is hash randomization, but I've seen this sort of thing as well on really old modules).

Broken dependency. Mirod already said it, but it's so common.

Incompatible operating system I might generalize to incompatible platform. That includes weirdness like different tmpfile behavior, NFS tmpdir, classic O/S issues, Win32 issues, big- vs. little-endian, compiler differences (e.g. the MSVC compiler).

Something that is similar to the above two but slightly different is wacky broken dependencies already installed. When I look at ActiveState build logs, some of their old systems have the right version of one of my dependencies, but for some reason it acts differently on their system than any other. Put another way, if my system has a broken/non-standard Math::BigInt installed, then I may get what seem like mysterious test failures when trying to install a module or its dependencies.

This may qualify as one of the others including broken module, but I've seen a number of cases where in my environment, 999/1000 test cases pass but one doesn't. This is often something like "testing interoperability with Obscure::Module" and Obscure::Module has changed something that invalidates the test. (Danger ahead) When I want the module for a one-off non-production experiment that has nothing to do with Obscure::Module I sometimes just force the install and typically everything works fine.

P.S. CPAN Testers, yay.

As a windows user, the most common reasons are:

- developer forgets that binary streams are different from perl text streams
- developer uses cross-platform file path handling, but compares with static strings in their tests
- developer decides to use file path handling to generate urls

A module dependency has changed its API in an incompatible way. PDF::Template ran into this when PDFlib removed functions PDF::Template used. (They were deprecated for 3 major releases - I had stopped updating PDF::Template for years before that.)

Wrong permissions needs to be broken out. There can be wrong permissions w.r.t.:

  • Directories use for build
  • Directories used for testing
  • Directories used for installation (vendor, arch, etc)
  • Resources necessary for testing (such as a database)

Another problem is filesystem is full. This could be /var, /tmp, or even /usr/local/lib (yes, I've seen this).

Tests could fail due to lack of external network connection. (Very early versions of LWP assumed a network connection.)

Dana, I’m uncomfortable with hash randomisation as an illustration of a too recent perl. It was not an incompatible change. What’s more, all the code that broke, visibly, already was broken, subtly. OTOH, not all of the breakage it exposed was relevant; some of it was in the test suite rather than the actual module, and the conditions that might trigger the bug never would happen there, so technically, it cannot be argued that all of the breakage was strictly necessary. So I’m on the fence… Still though – all of the code that broke was buggy, even if it was not an active bug.

A better example might be DaveM’s regexp work in 5.18 that changed how code blocks and interpolated regexp objects work in patterns. It was a welcome change toward sanity, but it was clearly a change that breaks some code that was working perfectly well before, e.g. Regexp::Grammars.

daxim says:

XS modules problems

1. Development environment (compiler, make) is not installed, Perl development files/headers are not installed. - Remedy: Install those files. Commonly an OS/distribution provides a meta package that pulls in all of them at once.
2. The C compiler that you are attempting to compile with does not match the C compiler that was used to compile Perl. - Remedy: Get GCC and the rest of the GNU tool-chain and brew your own Perl.

Windows problems

1. You have an ancient ActiveState Perl and ppm doesn't find the index because it's gone. - Remedy: Upgrade to a supported version.
2. You are following some outdated tutorial that involves downloading MSVC and nmake and nothing works. - Remedy: Since about 2011 ActiveState Perl comes with ppm and cpan working out of the box which pull in the development tools on first use. Use the automated tools (ppm, cpan) first, reserve manual installation only when things break.
3. You try to install the latest version of a module via ppm and it's not available. - Remedy: Look at to find out the cause, then contact module maintainer or ActiveState support accordingly for further assistance. Try to install with cpan.

Aristotle, you have a point that for hash-randomization breakage the code was wrong (and was *always* wrong, on every platform), but it is an example where an old module, perhaps not updated in many years, now fails to work.

Another example of this is the change to SvUPGRADE(sv), which used to return a value and changed to a void function in 5.17.8ish (it was indicated as being a void function in 2005). This broke a few Crypto modules, albeit the fix is really easy. But for a user who just wanted some upstream module, this means upgrading Perl made things stop working.

The module dependency issue is one reason I found to, when given the choice of two equal-for-my-use modules, one having 2 total chain non-core dependencies and the other having over 40, prefer the smaller.

I know. The complication that made me squirm is that, outside of some cases where the bug was in the test suite and inactive, those modules only seemed to work before upgrading to 5.18, even though they would install fine.

I think one of the huge problems is the inclusion of compiled or to be compiled libraries even more so if working on windows.

Early this year I tried to get the perl-bindings to gdal library running on windows. The errors are much to numerous to mention and the frustration was enormous. Most of the problems seems to arise in compiling the bindings with unmet dependencies not existing libraries and headers.

I guess it would be a good experience to install Geo::gdal on a windows machine. The frustrating part is that GIS development is becomming more and more common, but still impossible on perl.

I for myself gave up after two weeks of trying.

hash randomization
The best approach would have been to do this only in taint mode, and only for tainted values. As is, this adds non-repeatable behavior to every Perl program for the (theoretical) sake of some web devs.

They already were non-repeatable “for the sake of some web devs”, it just happened much more rarely and unpredictably. (If it did bite you, it was hard to reproduce what caused the problem.) Your complaint is a couple years late.

I put "PERL_HASH_SEED=0" in my init files and forgot about it back then, and I think that still saves me the trouble now. IIUC the recent changes make identical hashes in the same process behave differently, which is much more of a pain than their behaving differently across processes.

All of this to block a fiddly DoS attack seems a bit excessive, though I grant you it's "technically correct" (the best kind!).

The things people will do to avoid sprinkling a sort here and there… But hey, good for you.

Leave a comment

About sillymoose