---
name: import
signature: 'Module->import(LIST)'
since: 5.0
status: documented
categories: ["Scoping", "Modules"]
---

```{index} single: import; Perl built-in
```

*[Scoping](../perlfunc-by-category) · [Modules](../perlfunc-by-category)*

# 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`](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

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

Inside a module, the definition looks like:

```perl
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`](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:

```perl
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`](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`:

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

Callers then write:

```perl
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:

```perl
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`](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:

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

Explicit import list — only the names you ask for:

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

Empty list — load the file, touch nothing:

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

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

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

Calling `import` directly after a runtime [`require`](require):

```perl
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.

## See also

- [`use`](use) — the compile-time loader that invokes `import`;
  understanding one requires the other
- [`no`](no) — the mirror of `use`; calls `unimport` with the same
  argument-passing rules
- [`require`](require) — loads the file without calling `import`;
  pair with an explicit `Module->import(...)` when you want to
  defer or skip the compile-time dispatch
- [`package`](package) — defines the namespace that an `import`
  method populates from the caller's point of view
- [`caller`](caller) — how an `import` method discovers which
  package to install names into
- [`bless`](bless) — unrelated to `import`, but often invoked in
  the same module files; both shape how a package presents itself
  to its users