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

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

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

# __LINE__

A compile-time token that evaluates to the line number at which it
appears in the source.

`__LINE__` is not a function. It is a special token the parser
replaces, at compile time, with an integer literal — the line number
of the file position where the token sits. It is the standard way to
stamp a diagnostic, a log line, or a debug print with the exact
location that produced it, without paying for a [`caller`](caller) lookup at
runtime.

## Synopsis

```perl
__LINE__
```

## What you get back

An integer: the 1-based line number of the token within the current
compilation unit. The value is a plain number, usable anywhere a
number is — in arithmetic, in string interpolation, as a hash key, as
an argument to [`die`](die) or [`warn`](warn).

```perl
print __LINE__, "\n";        # prints the line number of this line
my $where = "line " . __LINE__;
```

Because the substitution happens at parse time, every occurrence of
`__LINE__` is effectively a different constant. Two copies on two
different lines produce two different numbers; a single `__LINE__`
inside a loop produces the same number on every iteration.

## Compile-time, not run-time

The value is frozen when the source is compiled. A common confusion:

```perl
sub where { return __LINE__ }     # returns the line where `__LINE__`
                                  # was written, i.e. the `sub` body's
                                  # line — NOT the caller's line
```

To capture the *caller's* line number, use [`caller`](caller):

```perl
sub where { my (undef, undef, $line) = caller; return $line }
```

Inside [`eval`](eval) of a string, `__LINE__` numbers the lines of the
string being compiled (starting at 1 for the first line of the
string), not the lines of the surrounding file.

## Altering the reported line number

The line number `__LINE__` reports is the line number the lexer
believes it is on. A `#line` directive resets that belief:

```perl
#line 1000 "virtual.pl"
print __LINE__, "\n";        # prints 1001
```

`#line NNN` on its own sets only the line number; `#line NNN "NAME"`
also changes what [`__FILE__`](__FILE__) reports. Code generators, template
engines, and preprocessors use this to make diagnostics point back at
the original source rather than the generated file. See
*Plain Old Comments (Not!)* in the perlsyn section of the reference
for the precise syntax and scope rules.

## Examples

Stamp a diagnostic with its origin:

```perl
die "bad input at ", __FILE__, " line ", __LINE__, "\n"
    unless defined $x;
```

`die` with a message that does **not** end in a newline already
appends `" at FILE line LINE.\n"`. Use the explicit form above only
when you want to control the formatting, or when you've suppressed
the automatic suffix with a trailing newline.

Log with file-and-line prefix:

```perl
sub logf {
    my ($file, $line) = (__FILE__, __LINE__);
    warn "[$file:$line] @_\n";
}
```

This logs the line where `__LINE__` was *written* — inside `logf` —
which is rarely what you want. The correct pattern uses [`caller`](caller):

```perl
sub logf {
    my (undef, $file, $line) = caller;
    warn "[$file:$line] @_\n";
}
```

Use `__LINE__` directly when you are marking *this* piece of code,
not the caller:

```perl
print STDERR "checkpoint at line ", __LINE__, "\n";
```

Relocate diagnostics with `#line`:

```perl
#line 42 "user-input.pl"
die "syntax error\n";        # dies reporting user-input.pl line 42
```

## Edge cases

- **Not a function, not callable.** `__LINE__()` is a syntax error.
  The token takes no arguments and has no parentheses form.
- **Not interpolated inside double-quoted strings.**
  `"see line __LINE__"` prints the literal string `see line __LINE__`.
  Concatenate instead: `"see line " . __LINE__`.
- **Not a valid hash-key bareword in the usual short form.**
  Inside `{ ... }` hash-key context, `$h{__LINE__}` works because the
  token is parsed as an expression, but `$h{ __LINE__ }` also works
  and is clearer. `$h{__LINE__ => 1}` parses `__LINE__` as a fat-comma
  bareword (i.e. the string `"__LINE__"`), which is almost never what
  you want — write `(__LINE__, 1)` or `(__LINE__() => 1)` if the
  literal value is wanted.
- **Inside string `eval`**, `__LINE__` counts from line 1 of the
  evaluated string. Prepend your own `#line` directive to the string
  to make diagnostics point at the enclosing file:

  ```perl
  my $code = qq{#line @{[__LINE__+1]} "@{[__FILE__]}"\n} . $user_code;
  eval $code;
  ```

- **Inside a here-doc body**, `__LINE__` evaluates to the line of the
  *opening* `<<` on the line where the here-doc is referenced, not
  lines inside the body — here-doc bodies are data, not code.
- **Heredoc and line directives.** `#line` inside a here-doc body has
  no effect; it is just text. `#line` only works as a
  beginning-of-line directive in code context.
- **Negative or zero line numbers.** `#line 0` is legal and makes the
  next physical line report as line 1 (the directive itself is line 0,
  the line after is line 1). Negative numbers are accepted but produce
  surprising diagnostics; don't.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`__FILE__`](__FILE__) — the companion token for the current source
  file name; 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 equivalent when you need the *caller's*
  line number, not the line of the call-site itself
- [`die`](die) — auto-appends `at FILE line LINE` when the message has
  no trailing newline, removing the need for explicit `__LINE__`
- [`warn`](warn) — same auto-location behavior as [`die`](die) for
  non-fatal diagnostics