---
name: push
signature: 'push ARRAY, LIST'
status: documented
categories: ["Arrays"]
---

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

*[Arrays](../perlfunc-by-category)*

# push

Append one or more values to the end of an array.

`push` adds every element of `LIST` to the end of `ARRAY`, in order.
It is the paired counterpart of [`pop`](pop) at the tail and of [`unshift`](unshift) /
[`shift`](shift) at the head. The array grows in place; no new array is
returned.

## Synopsis

```perl
push @arr, $val
push @arr, @more
push @arr, list, of, values
push @$aref, $val
```

## What you get back

The **new number of elements** in `ARRAY` after the append — i.e.
`scalar @arr` as it stands once `push` returns. Not the pushed
values, not the old length, not the array itself.

```perl
my @colors = ("red");
my $n = push @colors, "blue", "green";   # $n is 3
```

Useful when the push and the subsequent length check would otherwise
be two statements:

```perl
if (push @queue, $job > $limit) { ... }  # one call, count + test
```

## Examples

Basic append of a single value:

```perl
my @animals = ("cat");
push @animals, "mouse";                   # ("cat", "mouse")
```

Append several values in one call — each argument becomes its own
element:

```perl
my @colors = ("red");
push @colors, "blue", "green";            # ("red", "blue", "green")
```

Append the contents of another array. The second array is flattened
into the list, so its **elements** are appended, not the array as a
single item:

```perl
my @a = (1, 2);
my @b = (3, 4);
push @a, @b;                              # (1, 2, 3, 4)
```

Queue discipline — `push` at the tail, [`shift`](shift) at the head:

```perl
my @queue;
push @queue, $job;                        # enqueue
my $next = shift @queue;                  # dequeue
```

Stack discipline — `push` and [`pop`](pop) at the same end:

```perl
my @stack;
push @stack, $frame;                      # enter
my $top = pop @stack;                     # leave
```

Push onto an array held by reference. The reference must be
dereferenced with `@{ ... }` (or the short `@$ref` form) before
`push` sees an array:

```perl
my $aref = [1, 2];
push @$aref, 3;                           # $aref now refers to [1, 2, 3]
push @{ $aref }, 4, 5;                    # same, explicit deref
```

Count elements after appending without a temporary:

```perl
my $size = push @log, $entry;
warn "log is large: $size entries" if $size > 1000;
```

## Edge cases

- **Arrayref needs a deref.** `push $ref, $x` is a compile-time
  error in Perl 5.24+. Use `push @$ref, $x` or `push @{ $ref }, $x`.
  An experimental feature allowed a scalar first argument in
  5.14–5.22 and was removed; do not rely on it.
- **Array arguments auto-flatten.** `push @a, @b` appends `@b`'s
  elements individually. To append `@b` as a single nested entry
  you need an arrayref: `push @a, \@b` or `push @a, [ @b ]`.
- **Hash arguments also flatten.** `push @a, %h` appends alternating
  keys and values in hash iteration order — almost never what you
  want. Use `push @a, \%h` to store the hash by reference instead.
- **List context but scalar return.** `push` is documented as
  taking a `LIST` and therefore evaluates its arguments in list
  context, but the value `push` itself produces is always the
  resulting count. Inside `print push @a, @b` the count is what
  gets printed, not the array.
- **Empty `LIST`.** `push @a;` (no second argument) is a no-op and
  returns the current `scalar @a`. Legal and occasionally useful
  for "give me the count without modifying anything" — though
  `scalar @a` is clearer.
- **Tied arrays.** `push` on a tied array calls `PUSH` on the tied
  object if defined; otherwise it falls back to repeated `STORE`
  calls at `FETCHSIZE`-derived indices. See `perltie`.
- **Autovivification.** Pushing through an undef-valued reference
  vivifies an anonymous array:

  ```perl
  my %index;
  push @{ $index{$key} }, $value;         # $index{$key} becomes an arrayref
  ```

  After the first `push`, `$index{$key}` holds an arrayref
  containing `$value`. This is the standard idiom for building
  a hash-of-arrays incrementally.
- **Readonly array.** Pushing onto a readonly or fixed-size array
  (e.g. an element of `@_` bound to a caller's variable, or an
  array locked with [`Hash::Util::lock_value`](../../Hash/Util/lock_value)) raises
  `Modification of a read-only value attempted`.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`pop`](pop) — remove and return the last element; paired with
  `push` to form a stack
- [`shift`](shift) — remove and return the first element; paired
  with `push` to form a queue
- [`unshift`](unshift) — `push`'s mirror image at the head of the
  array; returns the new length the same way
- [`splice`](splice) — insert, remove, or replace any range;
  `push @a, @b` is equivalent to `splice @a, scalar @a, 0, @b`
- [`scalar`](scalar) — force scalar context on an array when you
  want the count without a `push`
- [`@ARGV`](../perlvar) — the canonical array most programs
  `push` onto or consume with [`shift`](shift)