---
name: untie
signature: 'untie VARIABLE'
status: documented
categories: ["Classes and OO"]
---

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

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

# untie

Break the binding between a variable and its tied class.

`untie` reverses a prior [`tie`](tie): after the call, `VARIABLE`
goes back to being a plain scalar, array, hash, or filehandle, and
subsequent reads and writes touch the raw storage rather than being
routed through the tied package's `FETCH`, `STORE`, and friends. If
the variable is not tied, `untie` is a no-op.

## Synopsis

```perl
untie VARIABLE
```

## What you get back

Returns a true value if the variable was tied and the binding was
removed, false otherwise. The return value is rarely checked — call
sites know whether they are unwinding a tie they set up themselves.

As a side effect, if the tied package defines an `UNTIE` method, it
is invoked on the tied object before the binding is dropped. `UNTIE`
receives the object and a count of any outstanding inner references
held to it (see *Edge cases* below).

## What it does

1. Locate the magic on `VARIABLE` that a prior [`tie`](tie) installed.
2. If the tied package provides `UNTIE`, call it on the object.
3. Remove the magic so the variable reverts to ordinary storage.
4. Release the interpreter's reference to the tied object. The object
   is destroyed (triggering `DESTROY` if defined) once no other
   references to it remain.

After `untie`, any value [`tied`](tied) previously returned for this
variable no longer corresponds to a live binding.

## Examples

Tie a hash, use it, then release it:

```perl
use Tie::File;
tie my @lines, 'Tie::File', 'log.txt' or die $!;
push @lines, "new entry";
untie @lines;                       # flush and release
```

A round-trip through [`tied`](tied) — grab the underlying object so
you can call a non-tied method on it, then drop the binding:

```perl
my $obj = tied %cache;
$obj->flush;
untie %cache;
```

`untie` on a variable that was never tied is harmless:

```perl
my %h;
untie %h;                           # no-op, no warning
```

An `UNTIE` hook that runs before the binding goes away:

```perl
package My::Tied;
sub TIEHASH { bless {}, shift }
sub UNTIE   { my ($self, $count) = @_;
              warn "untie with $count outstanding refs" if $count }
# ...
tie   my %h, 'My::Tied';
untie %h;                           # calls My::Tied::UNTIE($obj, 0)
```

## Edge cases

- **Outstanding inner references**: if code stashed the object
  returned by [`tie`](tie) or [`tied`](tied) somewhere that still
  holds it at the moment `untie` runs, Perl issues

  ```
  untie attempted while N inner references still exist
  ```

  under `use warnings`. The binding is removed anyway, but those
  stashed references continue to point at the now-detached object.
  Drop those references first, or accept that they will now see the
  un-tied object in isolation.
- **Calling `untie` on a non-tied variable** is a no-op. No warning,
  no error, no method call.
- **Filehandle tie**: `untie *FH` removes the tie installed by
  `tie *FH, $class, ...`. The underlying glob and any real file
  descriptor behind it are unaffected — `untie` does not
  [`close`](close).
- **`UNTIE` is optional**: if the tied package does not define one,
  the binding is simply removed. Do not rely on `UNTIE` running;
  many tied classes omit it.
- **Destruction order**: `untie` does not itself call `DESTROY`. The
  object is destroyed when its refcount hits zero, which may be
  immediately after `untie` (if nothing else holds it) or later (if
  the caller kept a copy from [`tied`](tied)).
- **Localised tied variables**: a tie installed inside a scope on a
  [`local`](local)ised variable is undone automatically when the
  scope exits; you do not need an explicit `untie`, and calling one
  is harmless.

## Differences from upstream

Fully compatible with upstream Perl 5.42.

## See also

- [`tie`](tie) — install the binding that `untie` removes; shows the
  full set of tie-hook method names
- [`tied`](tied) — fetch the object currently bound to a tied
  variable, typically just before calling `untie` on it
- [`bless`](bless) — `tie` blesses the object it is given; `untie`
  does not unbless, it only detaches the variable from it
- [`ref`](ref) — inspect what kind of reference [`tied`](tied)
  returned before deciding to `untie`
- [`local`](local) — scope-bounded alternative when you want the
  tie to go away on block exit without an explicit `untie`