---
name: package
signature: 'package NAMESPACE'
signatures:
  - 'package NAMESPACE'
  - 'package NAMESPACE VERSION'
  - 'package NAMESPACE BLOCK'
  - 'package NAMESPACE VERSION BLOCK'
since: 5.0
status: documented
categories: ["Scoping", "Modules", "Classes and OO"]
---

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

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

# package

Declare the compile-time namespace for the declarations that follow.

`package` tells the compiler which symbol table to use when it resolves
unqualified names in the code it is about to parse. It does **not**
create a package in any run-time sense — packages spring into existence
the first time something is stored in them. What a `package` statement
really does is re-point the compiler: from here on, `$foo` means
`$NAMESPACE::foo`, `&bar` means `&NAMESPACE::bar`, and so on, until the
next `package` statement or the end of the enclosing scope.

## Synopsis

```perl
package NAME;
package NAME VERSION;
package NAME     { ... }
package NAME VER { ... }
```

## What you get back

`package` is a compile-time directive, not an expression. It has no
useful runtime value — treat it as a statement. Its effect is on the
parser: all subsequent unqualified identifiers resolve in `NAME`'s
symbol table until scope ends.

The form with `VERSION` has one visible side effect: it sets
[`$NAME::VERSION`](../perlvar) to a [`version`](../../version) object
built from `VERSION`. This happens exactly once per `package NAME
VERSION` statement, at compile time.

## Global state it touches

- **The current compile-time package.** Every `package` statement
  replaces it for the rest of the scope. [`__PACKAGE__`](__PACKAGE__)
  returns the current value at any point in the source.
- [`$NAME::VERSION`](../perlvar) — set when the `VERSION` argument
  is provided. Set it only once per package.
- The target symbol table (stash) is created on first use. Nothing
  is populated by the `package` statement itself; subsequent
  declarations ([`sub`](sub), [`our`](our), assignments to
  `$NAME::foo`, etc.) fill it.

## The four forms

### `package NAMESPACE`

Switches the compile-time package to `NAMESPACE` from this point to
the end of the current scope (enclosing block, file, or
[`eval`](eval)). This is the classic "one package per file" form:

```perl
package My::Thing;

sub new { ... }         # defines &My::Thing::new
our $count = 0;         # defines $My::Thing::count

1;
```

### `package NAMESPACE VERSION`

Same scoping as the bare form, plus it sets
[`$NAMESPACE::VERSION`](../perlvar) to a [`version`](../../version)
object. `VERSION` must be a **strict** version literal: either a
positive decimal (`1.23`, `0.001`) or a dotted-decimal v-string with
a leading `v` and at least three components (`v1.2.3`). Exponent
notation is not allowed.

```perl
package My::Thing 1.042;
package My::Thing v1.2.3;
```

Set `$VERSION` only once per package — a second `package NAME
VERSION` statement in the same package overwrites the first, and
[`use Module VERSION`](use) consumers see only the final value.

### `package NAMESPACE BLOCK`

Lexically scopes the package switch to `BLOCK`. Inside the braces the
compile-time package is `NAMESPACE`; **outside the closing brace the
previous package is restored**. This is the only form that reverts
automatically.

```perl
package Outer;
our $x = 1;             # $Outer::x

package Inner {
    our $y = 2;         # $Inner::y
}

our $z = 3;             # $Outer::z again
```

### `package NAMESPACE VERSION BLOCK`

The block form with a version literal. Scope reverts at the closing
brace; [`$NAMESPACE::VERSION`](../perlvar) stays set.

```perl
package My::Sub v0.9.1 {
    sub ping { "pong" }
}
```

## What `package` does and does not scope

`package` affects **dynamic (package) variables** and unqualified
name resolution. It does not affect lexicals:

- [`my`](my), [`state`](state) — created in the lexical pad, invisible
  to package lookup. A `package` statement does nothing to them.
- [`local`](local) — dynamically scopes a package variable, which
  still belongs to whatever package its fully-qualified name names.
- [`our`](our) — declares a lexical alias to a package variable in
  the *current compile-time package*. This is the mechanism that
  lets `our $count` inside `package My::Thing` alias
  `$My::Thing::count`.

Switching packages after an `our` declaration does not retarget the
alias: the alias was bound to the package in effect when `our` was
compiled.

```perl
package Foo;
our $x;                 # aliases $Foo::x
package Bar;
$x = 1;                 # still writes $Foo::x
```

## Interaction with `use v5.36` and newer

[`use v5.36`](use) (and any `use v5.36` or later) enables
`strict` and `warnings` implicitly. Once strict
is on, unqualified package variables require an [`our`](our)
declaration (or full qualification). Combined with a `package`
statement, the idiomatic modern file skeleton is:

```perl
package My::Thing 1.00;

use v5.36;              # strict, warnings, say, signatures, ...

our @EXPORT_OK = qw(thingify);

sub thingify { ... }

1;
```

The `package NAME VERSION` form and `use VERSION` are independent:
the first sets `$My::Thing::VERSION`; the second enables language
features for the current file.

## Special identifiers that always mean `main::`

A small set of identifiers are forced into the `main::` package
regardless of the current `package`:

- `STDIN`, `STDOUT`, `STDERR`, `ARGV`, `ARGVOUT`
- `@ARGV`, `@INC`, `%ENV`, `%SIG`, `%INC`
- All punctuation variables: [`$_`](../perlvar), [`$!`](../perlvar),
  [`$@`](../perlvar), [`@_`](../perlvar), etc.

Writing to `$!` inside `package Foo` still writes to `$main::!`. This
is by design: these names would be useless if they moved with the
package.

## Examples

A minimal module file. The file name must match the package name
([`require`](require) translates `::` to the directory separator):

```perl
# lib/My/Greeter.pm
package My::Greeter 1.00;
use v5.36;

sub new  { my ($cls, %a) = @_; bless { %a }, $cls }
sub greet { my $self = shift; "hello, $self->{name}\n" }

1;
```

Two packages in one file using the block form. Scope reverts
automatically, so the `1;` at the bottom belongs to no package in
particular — it's evaluated in whichever package was active at the
top of the file (`main` for a script, the file's own package for a
module):

```perl
package My::Thing {
    sub do_stuff { ... }
}

package My::Thing::Helper {
    sub helper { ... }
}
```

Switching back and forth in the statement form — legal but rarely
what you want:

```perl
package A;
sub one { 1 }           # &A::one

package B;
sub two { 2 }           # &B::two

package A;
sub three { 3 }         # &A::three
```

Setting a version and reading it back. Note that `$VERSION` is a
`version` object, not a plain string; stringify or compare with
[`version`](../../version):

```perl
package Foo 1.23;

say $Foo::VERSION;      # 1.23
say ref $Foo::VERSION;  # version
```

[`our`](our) inside a package gives you a lexically-scoped alias
to a package variable — the canonical way to declare module-level
globals under `strict`:

```perl
package Counter;
use v5.36;

our $count = 0;         # aliases $Counter::count
sub bump { $count++ }
```

## Edge cases

- **`package NAMESPACE VERSION` accepts only strict version
  literals.** Exponent notation (`1e3`), non-numeric strings, and
  two-component v-strings (`v1.2`) are compile errors.
- **Setting `$VERSION` twice** in the same package (whether by two
  `package NAME VERSION` statements or by explicit assignment after a
  `package NAME VERSION`) is legal but confusing — [`use Module
  VERSION`](use) checks the final value, and CPAN tooling reads
  whichever one it finds first. Declare the version once.
- **The block form is a separate lexical scope**. [`my`](my) and
  [`state`](state) variables declared inside a `package NAME { ... }`
  are not visible outside, just like any other block.
- **`package NAMESPACE` without a trailing statement or block**
  affects the rest of the file. A `package` at the top of a script
  permanently switches the script out of `main`, which means
  `$main::ARGV[0]` is still your argument list but freshly declared
  globals belong to the new package. This is almost never what a
  script wants.
- **A file that contains only `package Foo;` and no other code**
  still compiles cleanly and creates the `Foo::` stash on first
  reference — but `require`ing it returns the value of the last
  statement, which is the `package` statement itself (false). Put
  `1;` at the end of every module file.
- **Nested block forms** restore the immediately enclosing package,
  not `main`:

  ```perl
  package Outer;
  package Inner {
      package Innermost {
          # __PACKAGE__ is Innermost
      }
      # __PACKAGE__ is Inner again
  }
  # __PACKAGE__ is Outer again
  ```
- **`package` inside [`eval`](eval)**. The package switch is scoped
  to the `eval` body. Symbols created during the `eval` persist in
  their stashes (stashes are global), but the compile-time package
  reverts when the `eval` ends.
- **Apostrophe as package separator** (`$main'sail` for
  `$main::sail`) is still parsed for compatibility with Perl 4 code
  but is deprecated. Do not write it; mention it only when reading
  ancient code.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`use`](use) — load a module at compile time and import symbols
  from its package; typically paired with a `package` declaration
  at the top of the loaded file
- [`require`](require) — load a module or file at runtime; the
  loaded file's `package` statement determines which stash its
  declarations populate
- [`bless`](bless) — associate a reference with a package so method
  calls dispatch to that package's subs; the glue between `package`
  and OO
- [`my`](my) — declare a lexical variable that `package` does
  **not** affect; the counterpart to package globals
- [`our`](our) — declare a lexical alias to a package variable in
  the current compile-time package; the strict-safe way to use
  module-level globals
- [`local`](local) — dynamically scope a package variable's value
  without changing which package it belongs to