Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
local::lib(3)	      User Contributed Perl Documentation	 local::lib(3)

       local::lib - create and use a local lib/	for perl modules with PERL5LIB

       In code -

	 use local::lib; # sets	up a local lib at ~/perl5

	 use local::lib	'~/foo'; # same, but ~/foo

	 # Or...
	 use FindBin;
	 use local::lib	"$FindBin::Bin/../support";  # app-local support library

       From the	shell -

	 # Install LWP and its missing dependencies to the '~/perl5' directory
	 perl -MCPAN -Mlocal::lib -e 'CPAN::install(LWP)'

	 # Just	print out useful shell commands
	 $ perl	-Mlocal::lib
	 PERL_MB_OPT='--install_base /home/username/perl5'; export PERL_MB_OPT;
	 PERL_MM_OPT='INSTALL_BASE=/home/username/perl5'; export PERL_MM_OPT;
	 PERL5LIB="/home/username/perl5/lib/perl5"; export PERL5LIB;
	 PATH="/home/username/perl5/bin:$PATH";	export PATH;

       From a .bashrc file -

	 [ $SHLVL -eq 1	] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"

   The bootstrapping technique
       A typical way to	install	local::lib is using what is known as the
       "bootstrapping" technique.  You would do	this if	your system
       administrator hasn't already installed local::lib.  In this case,
       you'll need to install local::lib in your home directory.

       Even if you do have administrative privileges, you will still want to
       set up your environment variables, as discussed in step 4. Without
       this, you would still install the modules into the system CPAN
       installation and	also your Perl scripts will not	use the	lib/ path you
       bootstrapped with local::lib.

       By default local::lib installs itself and the CPAN modules into

       Windows users must also see "Differences	when using this	module under

       1.  Download and	unpack the local::lib tarball from CPAN	(search	for
	   "Download" on the CPAN page about local::lib).  Do this as an
	   ordinary user, not as root or administrator.	 Unpack	the file in
	   your	home directory or in any other convenient location.

       2.  Run this:

	     perl Makefile.PL --bootstrap

	   If the system asks you whether it should automatically configure as
	   much	as possible, you would typically answer	yes.

	   In order to install local::lib into a directory other than the
	   default, you	need to	specify	the name of the	directory when you
	   call	bootstrap, as follows:

	     perl Makefile.PL --bootstrap=~/foo

       3.  Run this: (local::lib assumes you have make installed on your

	     make test && make install

       4.  Now we need to setup	the appropriate	environment variables, so that
	   Perl	starts using our newly generated lib/ directory. If you	are
	   using bash or any other Bourne shells, you can add this to your
	   shell startup script	this way:

	     echo '[ $SHLVL -eq	1 ] && eval "$(perl -I$HOME/perl5/lib/perl5 -Mlocal::lib)"' >>~/.bashrc

	   If you are using C shell, you can do	this as	follows:

	     echo $SHELL
	     echo 'eval	`perl -I$HOME/perl5/lib/perl5 -Mlocal::lib`' >>	~/.cshrc

	   If you passed to bootstrap a	directory other	than default, you also
	   need	to give	that as	import parameter to the	call of	the local::lib
	   module like this way:

	     echo '[ $SHLVL -eq	1 ] && eval "$(perl -I$HOME/foo/lib/perl5 -Mlocal::lib=$HOME/foo)"' >>~/.bashrc

	   After writing your shell configuration file,	be sure	to re-read it
	   to get the changed settings into your current shell's environment.
	   Bourne shells use ".	~/.bashrc" for this, whereas C shells use
	   "source ~/.cshrc".

       If you're on a slower machine, or are operating under draconian disk
       space limitations, you can disable the automatic	generation of manpages
       from POD	when installing	modules	by using the "--no-manpages" argument
       when bootstrapping:

	 perl Makefile.PL --bootstrap --no-manpages

       To avoid	doing several bootstrap	for several Perl module	environments
       on the same account, for	example	if you use it for several different
       deployed	applications independently, you	can use	one bootstrapped
       local::lib installation to install modules in different directories
       directly	this way:

	 cd ~/mydir1
	 perl -Mlocal::lib=./
	 eval $(perl -Mlocal::lib=./)  ### To set the environment for this shell alone
	 printenv		       ### You will see	that ~/mydir1 is in the	PERL5LIB
	 perl -MCPAN -e	install	...    ### whatever modules you	want
	 cd ../mydir2
	 ... REPEAT ...

       When used in a ".bashrc"	file, it is recommended	that you protect
       against re-activating a directory in a sub-shell.  This can be done by
       checking	the $SHLVL variable as shown in	synopsis.  Without this, sub-
       shells created by the user or other programs will override changes made
       to the parent shell's environment.

       If you are working with several "local::lib" environments, you may want
       to remove some of them from the current environment without disturbing
       the others.  You	can deactivate one environment like this (using	bourne

	 eval $(perl -Mlocal::lib=--deactivate,~/path)

       which will generate and run the commands	needed to remove "~/path" from
       your various search paths. Whichever environment	was activated most
       recently	will remain the	target for module installations. That is, if
       you activate "~/path_A" and then	you activate "~/path_B", new modules
       you install will	go in "~/path_B". If you deactivate "~/path_B" then
       modules will be installed into "~/pathA"	-- but if you deactivate
       "~/path_A" then they will still be installed in "~/pathB" because pathB
       was activated later.

       You can also ask	"local::lib" to	clean itself completely	out of the
       current shell's environment with	the "--deactivate-all" option.	For
       multiple	environments for multiple apps you may need to include a
       modified	version	of the "use FindBin" instructions in the "In code"
       sample above.  If you did something like	the above, you have a set of
       Perl modules at "~/mydir1/lib". If you have a script at
       "~/mydir1/scripts/", you need	to tell	it where to find the
       modules you installed for it at "~/mydir1/lib".

       In "~/mydir1/scripts/":

	 use strict;
	 use warnings;
	 use local::lib	"$FindBin::Bin/..";  ### points	to ~/mydir1 and	local::lib finds lib
	 use lib "$FindBin::Bin/../lib";     ### points	to ~/mydir1/lib

       Put this	before any BEGIN { ... } blocks	that require the modules you

   Differences when using this module under Win32
       To set up the proper environment	variables for your current session of
       "CMD.exe", you can use this:

	 C:\>perl -Mlocal::lib
	 set PERL_MB_OPT=--install_base	C:\DOCUME~1\ADMINI~1\perl5
	 set PERL5LIB=C:\DOCUME~1\ADMINI~1\perl5\lib\perl5
	 set PATH=C:\DOCUME~1\ADMINI~1\perl5\bin;%PATH%

	 ### To	set the	environment for	this shell alone
	 C:\>perl -Mlocal::lib > %TEMP%\tmp.bat	&& %TEMP%\tmp.bat && del %TEMP%\tmp.bat
	 ### instead of	$(perl -Mlocal::lib=./)

       If you want the environment entries to persist, you'll need to add them
       to the Control Panel's System applet yourself or	use

       The "~" is translated to	the user's profile directory (the directory
       named for the user under	"Documents and Settings" (Windows XP or
       earlier)	or "Users" (Windows Vista or later)) unless $ENV{HOME} exists.
       After that, the home directory is translated to a short name (which
       means the directory must	exist) and the subdirectories are created.


       local::lib also supports	PowerShell, and	can be used with the
       "Invoke-Expression" cmdlet.

	 Invoke-Expression "$(perl -Mlocal::lib)"

       The version of a	Perl package on	your machine is	not always the version
       you need.  Obviously, the best thing to do would	be to update to	the
       version you need.  However, you might be	in a situation where you're
       prevented from doing this.  Perhaps you don't have system administrator
       privileges; or perhaps you are using a package management system	such
       as Debian, and nobody has yet gotten around to packaging	up the version
       you need.

       local::lib solves this problem by allowing you to create	your own
       directory of Perl packages downloaded from CPAN (in a multi-user
       system, this would typically be within your own home directory).	 The
       existing	system Perl installation is not	affected; you simply invoke
       Perl with special options so that Perl uses the packages	in your	own
       local package directory rather than the system packages.	 local::lib
       arranges	things so that your locally installed version of the Perl
       packages	takes precedence over the system installation.

       If you are using	a package management system (such as Debian), you
       don't need to worry about Debian	and CPAN stepping on each other's
       toes.  Your local version of the	packages will be written to an
       entirely	separate directory from	those installed	by Debian.

       This module provides a quick, convenient	way of bootstrapping a user-
       local Perl module library located within	the user's home	directory. It
       also constructs and prints out for the user the list of environment
       variables using the syntax appropriate for the user's current shell (as
       specified by the	"SHELL"	environment variable), suitable	for directly
       adding to one's shell configuration file.

       More generally, local::lib allows for the bootstrapping and usage of a
       directory containing Perl modules outside of Perl's @INC. This makes it
       easier to ship an application with an app-specific copy of a Perl
       module, or collection of	modules. Useful	in cases like when an upstream
       maintainer hasn't applied a patch to a module of	theirs that you	need
       for your	application.

       On import, local::lib sets the following	environment variables to
       appropriate values:


       When possible, these will be appended to	instead	of overwritten

       These values are	then available for reference by	any code after import.

       See lib::core::only for one way to do this - but	note that there	are a
       number of caveats, and the best approach	is always to perform a build
       against a clean perl (i.e. site and vendor as close to empty as

       Options are values that can be passed to	the "local::lib" import
       besides the directory to	use. They are specified	as "use	local::lib
       '--option'[, path];" or "perl -Mlocal::lib=--option[,path]".

       Remove the chosen path (or the default path) from the module search
       paths if	it was added by	"local::lib", instead of adding	it.

       Remove all directories that were	added to search	paths by "local::lib"
       from the	search paths.

       Specify the shell type to use for output.  By default, the shell	will
       be detected based on the	environment.  Should be	one of:	"bourne",
       "csh", "cmd", or	"powershell".

       Prevents	"local::lib" from creating directories when activating dirs.
       This is likely to cause issues on Win32 systems.

       Arguments: $path
       Return value: None

       Attempts	to create the given path, and all required parent directories.
       Throws an exception on failure.

       Arguments: $path
       Return value: None

       Prints to standard output the variables listed above, properly set to
       use the given path as the base directory.

       Arguments: $path
       Return value: %environment_vars

       Returns a hash with the variables listed	above, properly	set to use the
       given path as the base directory.

       Arguments: $path
       Return value: None

       Constructs the %ENV keys	for the	given path, by calling

       Arguments: None
       Return value: @paths

       Returns a list of active	"local::lib" paths, according to the
       "PERL_LOCAL_LIB_ROOT" environment variable and verified against what is
       really in @INC.

       Arguments: $path
       Return value: $install_base_perl_path

       Returns a path describing where to install the Perl modules for this
       local library installation. Appends the directories "lib" and "perl5"
       to the given path.

       Arguments: $path
       Return value: @lib_paths

       Returns the list	of paths perl will search for libraries, given a base
       path.  This includes the	base path itself, the architecture specific
       subdirectory, and perl version specific subdirectories.	These paths
       may not all exist.

       Arguments: $path
       Return value: $install_base_bin_path

       Returns a path describing where to install the executable programs for
       this local library installation.	Appends	the directory "bin" to the
       given path.

       Arguments: $path
       Return value: %installer_env_vars

       Returns a hash of environment variables that should be set to cause
       installation into the given path.

       Arguments: $path
       Return value: $base_path

       Builds and returns the base path	into which to set up the local module
       installation. Defaults to "~/perl5".

       Arguments: $path
       Return value: $home_path

       Attempts	to find	the user's home	directory. If installed, uses
       "File::HomeDir" for this	purpose. If no definite	answer is available,
       throws an exception.

       Arguments: $path
       Return value: $absolute_path

       Translates the given path into an absolute path.

       Arguments: $path
       Return value: $absolute_path

       Calls the following in a	pipeline, passing the result from the previous
       to the next, in an attempt to find where	to configure the environment
       for a local library installation: "resolve_empty_path",
       "resolve_home_path", "resolve_relative_path". Passes the	given path
       argument	to "resolve_empty_path"	which then returns a result that is
       passed to "resolve_home_path", which then has its result	passed to
       "resolve_relative_path".	The result of this final call is returned from

       Arguments: %attributes
       Return value: $local_lib

       Constructs a new	"local::lib" object, representing the current state of
       @INC and	the relevant environment variables.

       An arrayref representing	active "local::lib" directories.

       An arrayref representing	@INC.

       An arrayref representing	the PERL5LIB environment variable.

       An arrayref representing	the PATH environment variable.

       A hashref of extra environment variables	(e.g. "PERL_MM_OPT" and

       If set, "local::lib" will not try to create directories when activating

       Arguments: %attributes
       Return value: $local_lib

       Constructs a new	"local::lib" object based on the existing one,
       overriding the specified	attributes.

       Arguments: $path
       Return value: $new_local_lib

       Constructs a new	instance with the specified path active.

       Arguments: $path
       Return value: $new_local_lib

       Constructs a new	instance with the specified path deactivated.

       Arguments: None
       Return value: $new_local_lib

       Constructs a new	instance with all "local::lib" directories

       Arguments: [ $shelltype ]
       Return value: $shell_env_string

       Returns a string	to set up the "local::lib", meant to be	run by a

       Arguments: None
       Return value: %environment_vars

       Returns a hash with the variables listed	above, properly	set to use the
       given path as the base directory.

       Arguments: None
       Return value: None

       Constructs the %ENV keys	for the	given path, by calling

       Constructs the %ENV hash	using "setup_env_hash",	and set	up @INC.

       Be careful about	using local::lib in combination	with "make install
       UNINST=1".  The idea of this feature is that will uninstall an old
       version of a module before installing a new one.	However	it lacks a
       safety check that the old version and the new version will go in	the
       same directory. Used in combination with	local::lib, you	can
       potentially delete a globally accessible	version	of a module while
       installing the new version in a local place. Only combine "make install
       UNINST=1" and local::lib	if you understand these	possible consequences.

       o   Directory names with	spaces in them are not well supported by the
	   perl	toolchain and the programs it uses.  Pure-perl distributions
	   should support spaces, but problems are more	likely with dists that
	   require compilation.	A workaround you can do	is moving your
	   local::lib to a directory with spaces after you installed all
	   modules inside your local::lib bootstrap. But be aware that you
	   can't update	or install CPAN	modules	after the move.

       o   Rather basic	shell detection. Right now anything with csh in	its
	   name	is assumed to be a C shell or something	compatible, and
	   everything else is assumed to be Bourne, except on Win32 systems.
	   If the "SHELL" environment variable is not set, a Bourne-compatible
	   shell is assumed.

       o   Kills any existing PERL_MM_OPT or PERL_MB_OPT.

       o   Should probably auto-fixup CPAN config if not already done.

       o   On VMS and MacOS Classic (pre-OS X),	local::lib loads File::Spec.
	   This	means any File::Spec version installed in the local::lib will
	   be ignored by scripts using local::lib.  A workaround for this is
	   using "use lib "$local_lib/lib/perl5";" instead of using
	   "local::lib"	directly.

       o   Conflicts with ExtUtils::MakeMaker's	"PREFIX" option.  "local::lib"
	   uses	the "INSTALL_BASE" option, as it has more predictable and sane
	   behavior.  If something attempts to use the "PREFIX"	option when
	   running a Makefile.PL, ExtUtils::MakeMaker will refuse to run, as
	   the two options conflict.  This can be worked around	by temporarily
	   unsetting the "PERL_MM_OPT" environment variable.

       o   Conflicts with Module::Build's "--prefix" option.  Similar to the
	   previous limitation,	but any	"--prefix" option specified will be
	   ignored.  This can be worked	around by temporarily unsetting	the
	   "PERL_MB_OPT" environment variable.

       Patches very much welcome for any of the	above.

       o   On Win32 systems, does not have a way to write the created
	   environment variables to the	registry, so that they can persist
	   through a reboot.

       If you've configured local::lib to install CPAN modules somewhere in to
       your home directory, and	at some	point later you	try to install a
       module with "cpan -i Foo::Bar", but it fails with an error like:
       "Warning: You do	not have permissions to	install	into
       /usr/lib64/perl5/site_perl/5.8.8/x86_64-linux at
       /usr/lib64/perl5/5.8.8/Foo/" and buried within the	install	log is
       an error	saying "'INSTALL_BASE' is not a	known MakeMaker	parameter
       name", then you've somehow lost your updated ExtUtils::MakeMaker

       To remedy this situation, rerun the bootstrapping procedure documented

       Then, run "rm -r	~/.cpan/build/Foo-Bar*"

       Finally,	re-run "cpan -i	Foo::Bar" and it should	install	without

	   local::lib looks at the user's "SHELL" environment variable when
	   printing out	commands to add	to the shell configuration file.

	   On Win32 systems, "COMSPEC" is also examined.

       o   Perl	Advent article,	2011


	   Join	#local-lib on

       Matt S Trout <>

       auto_install fixes kindly sponsored by

       Patches to correctly output commands for	csh style shells, as well as
       some documentation additions, contributed by Christopher	Nehren

       Doc patches for a custom	local::lib directory, more cleanups in the
       english documentation and a german documentation	contributed by Torsten
       Raudssus	<>.

       Hans Dieter Pearcey <> sent in some additional tests	for
       ensuring	things will install properly, submitted	a fix for the bug
       causing problems	with writing Makefiles during bootstrapping,
       contributed an example program, and submitted yet another fix to	ensure
       that local::lib can install and bootstrap properly. Many, many thanks!

       pattern of Freenode IRC contributed the beginnings of the
       Troubleshooting section.	Many thanks!

       Patch to	add Win32 support contributed by Curtis	Jewell

       Warnings	for missing PATH/PERL5LIB (as when not running interactively)
       silenced	by a patch from	Marco Emilio Poleggi.

       Mark Stosberg <> provided the code for the now
       deleted '--self-contained' option.

       Documentation patches to	make win32 usage clearer by David Mertens
       <> (run4flat).

       Brazilian portuguese translation	and minor doc patches contributed by
       Breno G.	de Oliveira <>.

       Improvements to stacking	multiple local::lib dirs and removing them
       from the	environment later on contributed by Andrew Rodland

       Patch for Carp version mismatch contributed by Hakim Cassimally

       Rewrite of internals and	numerous bug fixes and added features
       contributed by Graham Knop <>.

       Copyright (c) 2007 - 2013 the local::lib	"AUTHOR" and "CONTRIBUTORS" as
       listed above.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.24.1			  2014-12-09			 local::lib(3)


Want to link to this manual page? Use this URL:

home | help