---
name: __FILE__
signature: '__FILE__'
since: 5.0
status: documented
categories: ["Control flow"]
---

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

*[Control flow](../perlfunc-by-category)*

# __FILE__

The name of the source file the token is compiled in.

`__FILE__` is a compile-time token, not a runtime function. At the
point the compiler reads it, it is replaced with a string literal
holding the filename the compiler is currently reading from. It takes
no arguments, is never called with parens, and has no runtime cost —
by the time your program runs, `__FILE__` has already become a plain
string constant.

Its one job is to let code identify the file it lives in, for error
messages, log lines, test diagnostics, and similar reporting.

## Synopsis

```perl
__FILE__
```

## What you get back

A string: the filename as the compiler knew it when it read this
token. For a script invoked as `perl /tmp/run.pl` the value is
`/tmp/run.pl`; for a module loaded through [`require`](require) or
[`use`](use) it is the path [`require`](require) resolved against
[`@INC`](../perlvar) (typically an absolute path). For code fed on
standard input or through `-e` it is `-` or `-e`
respectively.

Because substitution happens at compile time, the value is fixed for
each textual occurrence of the token. Two `__FILE__` tokens in
different files produce different strings; two in the same file
produce the same string.

## Global state it touches

None at runtime. At compile time the value is taken from the
compiler's current filename, which is the same value
[`caller`](caller) reports in list context as element `[1]` and which
[`die`](die) / [`warn`](warn) use to build their default
`"at FILE line LINE."` suffix.

That filename can be **rewritten** by a `#line` directive embedded in
the source — see *Edge cases* below. Once rewritten, `__FILE__`
tokens compiled after the directive report the new name.

## Examples

Identify the running script in a log line:

```perl
warn "started from ", __FILE__, "\n";
# started from /tmp/run.pl
```

Attach source location to a custom error without [`die`](die)'s
default suffix:

```perl
sub fail {
    my ($msg) = @_;
    die sprintf("%s at %s line %d\n", $msg, __FILE__, __LINE__);
}
```

Build a path relative to the current module, so resource files ship
alongside the code that loads them:

```perl
use File::Basename qw(dirname);
use File::Spec;
my $data = File::Spec->catfile(dirname(__FILE__), "data.txt");
```

Use `__FILE__` inside a string passed to [`eval`](eval) to keep error
reports pointing at the original source rather than at the anonymous
`(eval N)` buffer:

```perl
my $code = qq[\n#line ] . __LINE__ . qq[ "] . __FILE__ . qq["\n]
         . q[die "boom"];
eval $code;
# boom at <current file> line <current line>.
```

Distinguish "run as a script" from "loaded as a module" — the common
test is whether the file was invoked directly:

```perl
__PACKAGE__->run(@ARGV) if __FILE__ eq $0;
```

## Edge cases

- **Compile-time, not runtime.** `__FILE__` is a token the parser
  replaces with a string literal. It is not a function you can take a
  reference to; `\&__FILE__` is a syntax error. Stringify it, store
  it, or pass it — but you cannot defer its evaluation.
- **Stable per occurrence.** Calling the same subroutine from two
  different files does not change the `__FILE__` the subroutine body
  sees; that value was baked in when the subroutine was compiled.
  If you need the caller's filename, use [`caller`](caller).
- **`#line` directives rewrite the value.** A comment of the form
  `# line N "NAME"` at column zero resets both the line number and
  (optionally) the filename the compiler reports. Every `__FILE__`
  token compiled after such a directive picks up the new name. This
  is the mechanism code generators and template engines use to make
  errors point at the original `.tt` / `.pod` / `.xs` source instead
  of the generated `.pl`.

  ```perl
  # line 1 "config.tt"
  my $x = __FILE__;       # "config.tt"
  ```

  Full syntax of the directive is specified in
  `perlsyn` under *Plain Old Comments (Not!)*.
- **Modules.** Inside a module, `__FILE__` is the path
  [`require`](require) used to load the file — usually absolute and
  under an [`@INC`](../perlvar) root. Do not parse it as
  `Some/Module.pm`; use `dirname(__FILE__)` if you need the directory,
  not string surgery.
- **Special command-line sources.** Code from `-e` reports `-e`; code
  from `-E` reports `-e` as well; code piped on stdin reports `-`.
  String [`eval`](eval) without a `#line` directive reports
  `(eval N)` where `N` is the eval counter.
- **One-argument [`open`](open) and its `__FILE__` lookalike.** There
  is no `__FILE__` handle; the token has nothing to do with
  filehandles. `open(__FILE__)` does not open the current source
  file — it tries to open a file literally named after the token's
  expanded string, which is rarely what you want.
- **Not modifiable at runtime.** Assigning to `__FILE__` is a syntax
  error. The mechanism for changing what `__FILE__` reports is the
  `#line` directive at compile time; there is no runtime equivalent.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`__LINE__`](__LINE__) — companion compile-time token for the
  current line number; the two are almost always used together
- [`__PACKAGE__`](__PACKAGE__) — compile-time token for the current
  package name, same family of special tokens
- [`caller`](caller) — runtime lookup of the caller's filename, line,
  and package; use this when you need the caller's source location
  rather than your own
- [`die`](die) — appends `at FILE line LINE.` automatically; reach
  for `__FILE__` explicitly only when you suppress that suffix with
  a trailing newline
- `perlsyn` — the *Plain Old Comments (Not!)* section
  specifies the `#line` directive that rewrites `__FILE__`