LFS-POOL-UNPIN(1) Lustre User Utilities LFS-POOL-UNPIN(1)

# [NAME](#NAME)

lfs-pool-unpin - unpin files, directories or FIDs from an OST pool

# [SYNOPSIS](#SYNOPSIS)

`lfs pool unpin` \[**--pool** *POOL*] \[**--quiet**] \[**--file**] *FILE* | *DIRECTORY* ...

`lfs pool unpin` \[**--pool** *POOL*] \[**--quiet**] **--fid** *MOUNT* *FID* ...

# [DESCRIPTION](#DESCRIPTION)

The **lfs pool unpin** subcommand removes the restriction on the named *FILE*(s), and/or files in the named *DIRECTORY*(/ies), so that there are no longer restrictions on migrating the file from the named *POOL*.

**lfs pool unpin** removes a **pool** entry for the selected *POOL* from the **lustre.pin** attribute. If no matching entry is present, the command succeeds without modifying the attribute. When the last entry is removed, the **lustre.pin** attribute itself may be deleted.

When the **--pool** option is omitted, *POOL* is inferred from the primary mirror layout of each file or directory. If the layout does not have an associated pool, the operation fails for that target and an error message is printed.

The **--fid** form of the command operates on files referenced by Lustre FIDs beneath the filesystem mounted at *MOUNT*, while the default and **--file** forms operate on filesystem paths.

Updating the **lustre.pin** attribute requires both appropriate write permissions on the target and sufficient privileges on the MDT. If these checks fail the operation will return **EPERM**, typically due to the **mdt.enable\_pin\_gid** policy; see [**mdt.enable\_pin\_gid**(4)](/man/enterprise-packages/lustre/mdt.enable_pin_gid.4) for details.

# [OPTIONS](#OPTIONS)

[**--pool** **POOL**](#pool)

Name of the OST pool that should be unpinned from the specified files. The name must consist of only alphanumeric characters, underscores and hyphens, and may optionally be qualified with an *fsname* prefix (e.g. *fsname*.*POOL*), which is discarded before the pool name is used.

[**-f**, **--file**](#f)

Interpret remaining arguments as filesystem paths (this is the default if neither **--file** nor **--fid** is given).

[**-F**, **--fid** **MOUNT**](#F)

Interpret remaining arguments as Lustre FIDs within the filesystem mounted at *MOUNT*. This option is mutually exclusive with **--file**.

[**-q**, **--quiet**](#q)

Suppress per-target error messages (such as a target that cannot be opened or an unrecognized FID); the exit status still reflects any errors encountered.

[**-h**, **--help**](#h)

Display brief usage information for the **lfs pool unpin** subcommand.

# [EXIT STATUS](#EXIT_STATUS)

The **lfs pool unpin** command returns 0 if every target was pinned to the requested (or inferred) pool and is now unpinned, or 1 if one or more targets were not pinned there to begin with, could not be unpinned (for example due to insufficient privileges; see [**mdt.enable\_pin\_gid**(4)](/man/enterprise-packages/lustre/mdt.enable_pin_gid.4) for the MDT-side policy controlling which users may pin or unpin files), or otherwise did not end up unpinned; unpinning a target that had nothing to unpin is not treated as an error and does not modify **lustre.pin**. A non-zero exit status other than 1 is returned if any argument is invalid, a pool cannot be inferred when required, or a target could not be opened.

# [EXAMPLES](#EXAMPLES)

Unpin a directory tree and a single file from the pool scratch:

```
$ lfs pool unpin --pool scratch /mnt/testfs/proj /mnt/testfs/file
```

Unpin a file from the pool inferred from its primary mirror layout:

```
$ lfs pool unpin /mnt/testfs/file
```

Unpin a file referenced by FID from the pool scratch:

```
$ lfs pool unpin --pool scratch --fid /mnt/testfs 0x200000401:0x1:0x0
```

# [AVAILABILITY](#AVAILABILITY)

The **lfs pool unpin** command is part of the [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7) filesystem package since release 2.18.0.

# [SEE ALSO](#SEE_ALSO)

[**lfs**(1)](/man/enterprise-packages/lustre/lfs.1), [**lfs-pool**(1)](/man/enterprise-packages/lustre/lfs-pool.1), [**lfs-pool-pin**(1)](/man/enterprise-packages/lustre/lfs-pool-pin.1), [**lfs-pool-pin\_info**(1)](/man/enterprise-packages/lustre/lfs-pool-pin_info.1), [**llapi\_pool\_unpin\_file**(3)](/man/enterprise-packages/lustre/llapi_pool_unpin_file.3), [**mdt.enable\_pin\_gid**(4)](/man/enterprise-packages/lustre/mdt.enable_pin_gid.4), [**lustre**(7)](/man/enterprise-packages/lustre/lustre.7)

2026-09-14 Lustre

---

Document: lfs-pool-unpin(1) from lustre 2.17.60-r0 (Chainguard OS)
Source: https://github.com/lustre/lustre-release