
require VERSION
require EXPR


VERSION may be either a literal such as v5.24.1, which will be compared to $^V (or $PERL_VERSION in English), or a numeric argument of the form 5.024001, which will be compared to $]. An exception is raised if VERSION is greater than the version of the current Perl interpreter. Compare with use, which can do a similar check at compile time.

Specifying VERSION as a numeric argument of the form 5.024001 should generally be avoided as older less readable syntax compared to v5.24.1. Before perl 5.8.0 (released in 2002), the more verbose numeric form was the only supported syntax, which is why you might see it in older code.

require v5.24.1;    # run time version check
require 5.24.1;     # ditto
require 5.024_001;  # ditto; older syntax compatible
                      with perl 5.6


use Carp 'croak';
use version;

sub require {
    my ($filename) = @_;
        if ( $version > $^V ) {
           my $vn = $version->normal;
        return 1;

    if (exists $INC{$filename}) {
        return 1 if $INC{$filename};
        croak "Compilation failed in require";

    foreach $prefix (@INC) {
        if (ref($prefix)) {
        # (see text below about possible appending of .pmc
        # suffix to $filename)
        my $realfilename = "$prefix/$filename";
        $INC{$filename} = $realfilename;
        my $result = do($realfilename);
                     # but run in caller's namespace

        if (!defined $result) {
            $INC{$filename} = undef;
            croak $@ ? "$@Compilation failed in require"
        if (!$result) {
            delete $INC{$filename};
            croak "$filename did not return true value";
        $! = 0;
        return $result;



If EXPR is a bareword, require assumes a .pm extension and replaces :: with / in the filename for you, to make it easy to load standard modules. This form of loading of modules does not risk altering your namespace, however it will autovivify the stash for the required module.

In other words, if you try this:

require Foo::Bar;     # a splendid bareword

The require function will actually look for the Foo/ file in the directories specified in the @INC array, and it will autovivify the Foo::Bar:: stash at compile time.

But if you try this:

    my $class = 'Foo::Bar';
    require $class;       # $class is not a bareword

The require function will look for the Foo::Bar file in the @INC array and will complain about not finding Foo::Bar there. In this case you can do:

eval "require $class";

or you could do

require "Foo/";

Neither of these forms will autovivify any stashes at compile time and only have run time effects.

Now that you understand how require looks for files with a bareword argument, there is a little extra functionality going on behind the scenes. Before require looks for a .pm extension, it will first look for a similar filename with a .pmc extension. If this file is found, it will be loaded in place of any file ending in a .pm extension. This applies to both the explicit require "Foo/"; form and the require Foo::Bar; form.


Subroutine references are the simplest case. When the inclusion system walks through @INC and encounters a subroutine, this subroutine gets called with two parameters, the first a reference to itself, and the second the name of the file to be included (e.g., Foo/ The subroutine should return either nothing or else a list of up to four values in the following order:

  1. A reference to a scalar, containing any initial source code to prepend to the file or generator output.

  2. A filehandle, from which the file will be read.

  3. A reference to a subroutine. If there is no filehandle (previous item), then this subroutine is expected to generate one line of source code per call, writing the line into $_ and returning 1, then finally at end of file returning 0. If there is a filehandle, then the subroutine will be called to act as a simple source filter, with the line as read in $_. Again, return 1 for each valid line, and 0 after all lines have been returned. For historical reasons the subroutine will receive a meaningless argument (in fact always the numeric value zero) as $_[0].

  4. Optional state for the subroutine. The state is passed in as $_[1].



In other words, you can write:

push @INC, \&my_sub;
sub my_sub {


sub my_sub {
    my ($arrayref, $filename) = @_;
    # Retrieve $x, $y, ...
    my (undef, @parameters) = @$arrayref;


# In
package Foo;
sub new { ... }
sub Foo::INC {
    my ($self, $filename) = @_;

# In the main program

These hooks are also permitted to set the %INC entry corresponding to the files they have loaded. See "%INC" in perlvar.
