import#

Populate the caller’s namespace with names a module chooses to export.

import is not a built-in function. It is a class method a module defines so that use has somewhere to hand off the argument list. When you write use Module LIST, Perl loads the module and then calls Module->import(LIST) at compile time, in the package that contains the use statement. Whatever that method does — install subroutines into the caller’s stash, flip feature bits, set pragma flags — is the module’s entire import contract.

Most modules never write import by hand; they inherit it from Exporter and declare @EXPORT / @EXPORT_OK instead. Pragmas (strict, warnings, feature) write their own import because what they install is lexical state, not subroutines.

Synopsis#

Module->import;
Module->import(LIST);
Module->import(@symbols);

Inside a module, the definition looks like:

package My::Module;
sub import {
    my ($class, @args) = @_;
    # install names into caller's package
}

What you get back#

The return value of import is discarded by use. A module that is called directly as a method inherits whatever convention the author chose — by convention, return nothing useful.

The visible effect is in the caller’s package: after use Module qw(foo bar) returns, foo and bar are callable without a package prefix from the code that ran the use.

How `use` calls `import`#

use Module LIST is, in effect:

BEGIN {
    require Module;
    Module->import(LIST);
}

Three consequences fall out of that equivalence:

Compile time. import runs while the enclosing file is still being parsed. Any subroutine prototypes or lexical pragmas it installs are visible to the rest of the file from that point on. Anything done at runtime — opening files, reading configuration — happens earlier than a naive reading of the source suggests.
caller reflects the BEGIN block, not the surrounding subroutine. An import method that inspects caller(0) sees the package that wrote use Module, which is exactly what it wants; it does not see the subroutine that contains the use statement.
Absent list vs empty list. use Module with no list calls Module->import with no arguments — the module installs its defaults. use Module () with an explicit empty list skips the import call entirely. This is the idiom for “load the file but do not touch my namespace.”

no Module LIST is the mirror image: it calls Module->unimport(LIST) instead of import. Pragmas use this to turn features off for the enclosing lexical scope.

Defining an `import` method#

The common path is inheritance from Exporter:

package My::Utils;
use Exporter 'import';                 # installs Exporter::import
our @EXPORT_OK = qw(slurp trim);
sub slurp { ... }
sub trim  { ... }
1;

Callers then write:

use My::Utils qw(slurp trim);
slurp($path);

A hand-rolled import has the same shape as any method — it receives the class name as its first argument and the use argument list as the rest:

package My::Feature;
sub import {
    my ($class, @flags) = @_;
    my $caller = caller;
    no strict 'refs';
    for my $name (@flags) {
        *{ "${caller}::${name}" } = \&{ "${class}::${name}" };
    }
}

The caller’s package name comes from caller, not from $class — $class is whatever module the user named on the use line.

Examples#

Default import — whatever the module’s @EXPORT list contains:

use List::Util;                        # imports nothing by default
use File::Basename;                    # imports basename, dirname, ...

Explicit import list — only the names you ask for:

use List::Util qw(sum min max);
my $total = sum(1, 2, 3);              # 6

Empty list — load the file, touch nothing:

use POSIX ();                          # no POSIX::* names imported
my $pi = POSIX::acos(-1);              # fully qualified call

Importing from a pragma — lexical effect in the enclosing block:

use strict;
use warnings;
{
    no warnings 'uninitialized';       # unimport in this block only
    print "x=", $x, "\n";
}

Calling import directly after a runtime require:

require My::Plugin;
My::Plugin->import(@config);           # deferred to runtime on purpose

This pattern loads the module only when a code path actually needs it, trading compile-time checking for startup speed.

Edge cases#

No such thing as a built-in import. print import(@list) calls the subroutine named import in the current package (if one exists); it is not a language-level operator. Parsing rules apply as for any user-defined subroutine.
Omitted list vs empty list is the most common source of confusion. use Mod calls import; use Mod () does not. The () is not a stylistic empty — it is a signal.
Version argument runs VERSION, not import. use Mod 1.23 LIST calls Mod->VERSION(1.23) before Mod->import(LIST). A bare use Mod 1.23 is still a version check followed by a default import. To version-check and skip imports, write use Mod 1.23 ().
No import defined at all. If the module neither writes nor inherits an import, use Module LIST with a non-empty list does not error — the method call falls through silently as UNIVERSAL::can('import') returns false and use treats it as “nothing to do.” Non-empty LIST is then effectively ignored, which is almost never what the caller wanted.
import runs once per use statement, not once per process. use Mod qw(foo); use Mod qw(bar); calls import twice, even though the file is loaded only once — @INC / %INC gate the file load, not the method call.
Symbol installation is not automatic. Writing an import method that merely returns does nothing; you must assign into the caller’s stash (*{"${caller}::name"} = \&sub) or delegate to Exporter.
Pragmas typically install lexical state, not package-level subroutines. Their import calls functions like warnings::import_into or manipulates %^H; this is why a pragma’s effect is scoped to the enclosing block rather than persisting in the package.

Differences from upstream#

Fully compatible with upstream Perl 5.42.