Perl packages
last modified October 8, 2026
In this article we show how to organize Perl code into packages and modules.
A package is a separate namespace. It keeps variable and subroutine names from colliding with names in other parts of a program. Modules are files that contain packages and can be loaded by other programs.
Perl package block
The package keyword starts a new namespace. The block form
package NAME { ... } limits the namespace to the braces. In the
following example, we define a package with a variable and a subroutine.
#!/usr/bin/perl
use v5.34.0;
use warnings;
package Counter {
our $count = 0;
sub increment {
$count++;
return $count;
}
}
package main;
say Counter::increment();
say Counter::increment();
say $Counter::count;
The our variable and the increment subroutine belong to
the Counter package. Inside the package, we can use their short
names. Outside the package, we must use the fully qualified names.
package Counter {
our $count = 0;
sub increment {
$count++;
return $count;
}
}
The block contains the package variable $count and the subroutine
increment. Both are visible as Counter::count and
Counter::increment.
package main;
The package main; statement switches back to the main package, which
is the default package of a program.
$ perl counter.pl 1 2 2
Fully qualified names
A fully qualified name includes the package name, separated by ::.
The statement form package NAME; keeps the namespace active until the
next package statement or the end of the file. Variables declared
with our at file level belong to the main package.
#!/usr/bin/perl
use v5.34.0;
use warnings;
our $name = "main program";
package Animal;
our $sound = "...";
sub speak {
return "Animal says $sound";
}
package main;
say $name;
say $Animal::sound;
say Animal::speak();
say $main::name;
We call the subroutine and read the variable through their fully qualified names.
The main:: prefix refers to the same variable as the unqualified
$name.
our $sound = "...";
The our declaration creates the package variable $sound
in the Animal package, because the current package is
Animal at that point.
say Animal::speak();
We call the subroutine with the package name and ::, since we are
not inside the Animal package.
$ perl animal.pl main program ... Animal says ... main program
The __PACKAGE__ token
The __PACKAGE__ token evaluates to the name of the package in which
it appears. It is useful when a package needs to refer to its own name, for
example in log messages, without repeating the name.
#!/usr/bin/perl
use v5.34.0;
use warnings;
package Logger;
sub whoami {
return __PACKAGE__;
}
sub log_msg {
my ($msg) = @_;
my $pkg = __PACKAGE__;
return "[$pkg] $msg";
}
package main;
say Logger::whoami();
say Logger::log_msg("started");
say __PACKAGE__;
Inside the Logger package, __PACKAGE__ is
Logger. After the package main; statement, it is
main.
$ perl logger.pl Logger [Logger] started main
Writing a module
A module is a file with a .pm extension that contains a package.
By convention, the file path mirrors the package name, so package
Greeter is stored in Greeter.pm. Module files are often
kept in a lib/ directory. The file must end with a true value, which
is usually written as 1;.
The module below uses Exporter. The @EXPORT array lists
the names that are imported by default. The @EXPORT_OK array lists
the names that can be imported only when they are requested explicitly.
package Greeter;
use strict;
use warnings;
use Exporter 'import';
our @EXPORT = qw(greet);
our @EXPORT_OK = qw(farewell);
sub greet {
my ($name) = @_;
return "Hello, $name!";
}
sub farewell {
my ($name) = @_;
return "Goodbye, $name!";
}
1;
The use Exporter 'import'; line gives the module the
import method, which copies the requested names into the caller's
namespace.
our @EXPORT = qw(greet);
The greet subroutine is exported by default. A program that uses
Greeter can call greet without a prefix.
1;
The final 1; makes the file return a true value, so Perl considers
that the module loaded successfully.
The following script uses the default exports. Because the module is in the
lib/ directory, we pass -Ilib to add that directory to
the module search path.
#!/usr/bin/perl
use v5.34.0;
use warnings;
use Greeter;
say greet("Lucy");
say greet("Tom");
The use Greeter; statement loads lib/Greeter.pm at
compile time and imports the names listed in @EXPORT.
$ perl -Ilib main.pl Hello, Lucy! Hello, Tom!
Importing with EXPORT_OK
Names in @EXPORT_OK are not imported unless the program asks for
them. We list the wanted names after the module name. Other exported names can
still be called with their fully qualified names.
#!/usr/bin/perl
use v5.34.0;
use warnings;
use Greeter qw(farewell);
say farewell("Lucy");
say Greeter::greet("Tom");
We import only farewell. The greet subroutine is not
imported into main, so we call it as Greeter::greet.
$ perl -Ilib main.pl Goodbye, Lucy! Hello, Tom!
Perl use lib
The use lib pragma adds directories to the front of the module search
path @INC. It is an alternative to passing -I on the
command line. The directory is resolved relative to the current working
directory, so the script below must be run from the directory that contains
lib/.
#!/usr/bin/perl
use v5.34.0;
use warnings;
use lib 'lib';
use Greeter;
say greet("Lucy");
say "Loaded from: $INC{'Greeter.pm'}";
The %INC hash records the path of each loaded file. We use it to
show where Greeter.pm was found.
$ perl main.pl Hello, Lucy! Loaded from: lib/Greeter.pm
Perl use vs require
The use statement loads a module at compile time and calls its
import method. The require function loads a module at
run time and does not import any names. Because require runs during
execution, we can check whether the load succeeded. In the example, we wrap
require in eval to catch the error for a missing module.
#!/usr/bin/perl
use v5.34.0;
use warnings;
use lib 'lib';
if (eval { require Greeter; 1 }) {
say "Greeter loaded";
say Greeter::greet("Lucy");
} else {
print "Cannot load Greeter: $@";
}
if (!eval { require Missing::Module; 1 }) {
my ($msg) = $@ =~ /^(Can't locate \S+)/;
say "Error: $msg";
}
The require call does not import greet, so we use the
fully qualified name. The eval block returns true only if
require succeeds; otherwise, the error message is stored in
$@.
if (!eval { require Missing::Module; 1 }) {
my ($msg) = $@ =~ /^(Can't locate \S+)/;
say "Error: $msg";
}
The module Missing::Module does not exist, so require
dies. We print only the first part of the error message.
$ perl main.pl Greeter loaded Hello, Lucy! Error: Can't locate Missing/Module.pm
In this article we have covered packages, modules, the Exporter
module, use lib, and require in Perl.
Author
List all Perl tutorials.