NILFS2

Related articles
File systems
NILFS2
(New Implementation of a Log-structured File System) is a log-structured file system supporting versioning of the entire file system and continuous snapshotting, which allows users to even restore files mistakenly overwritten or destroyed just a few seconds ago.
It was developed by Nippon Telegraph and Telephone Corporation (NTT) CyberSpace Laboratories and a community from all over the world. NILFS was released under the terms of the GNU General Public License (GPL).
NILFS2 is continously snapshoted, as such it can be considered versioning file system where file system automatically keeps past versions of every file.
Note
NILFS2 might not be best choice for mechanical hard drives due to its log structured design causing fragmentation.
As of 2025-04-22 NILFS2 does not implement atime (access time), extended atributes and Posix ACLs (Posix Access Control Lists). If your workflow is dependent on these, do not use NILFS2. It also currently lacks proper fsck so in the case of severe error it might not be recoverable.
See
Current status
to see what is and is not implemented.
Tip
While most of NILFS2 tools allow omiting device file argument, it is recomended to always use it in setups with multiple NILFS2 file systems to prevent accidentaly modifying wrong file system.
Creating a NILFS2 file system
This article assumes the device has
partitions
already setup.
Install
nilfs-utils
.  Use
mkfs.nilfs2
to format the target partition referred to as
/dev/sdxY
:
# mkfs.nilfs2 -L mylabel
/dev/sdxY
See
mkfs.nilfs2(8)
for all available options.
Changing label
Nilfs-tune command should be used only for unmounted file systems.
# nilfs-tune -L newlabel
/dev/sdxY
Mounting
The file system can then be mounted manually or via other mechanisms:
# mount /dev/sdxY /mnt/foo
Mount options
Error handling
errors=continue
/
remount-ro
/
panic
Specifies what NILFS2 should do on file system error. Continue Ignores error, remount-ro remounts file system read-only and panic halts the system.
Discard
discard
/
nodiscard
Enable/disable
TRIM
See
mount.nilfs2(8)
for all available options.
Snapshots
NILFS2 has two types of snapshots, checkpoints and snapshots. They are often written as
cp
and
ss
respectively.
NILFS2 creates checkpoints on every write automatically. Checkpoint is snapshot that can be automatically deleted by NILFS2 garbage collector to free up space when file system is filled up or when user manually prompts it for cleaning.
Snapshots have to be manually converted from checkpoints and are never deleted automatically. They can be mounted to recover data from them.
Listing snapshots
Checkpoints and snapshots can be listed with:
lscp /dev/sdxY
CNO        DATE     TIME  MODE  FLG      BLKCNT       ICNT
     1  2025-04-14 21:35:06   cp    -     10181423     554012
     2  2025-04-14 22:17:38   cp    -     10181423     554012
     3  2025-04-14 22:18:22   cp    -     10181423     554012
     4  2025-04-14 22:28:56   cp    -     10181423     554012
     5  2025-04-14 22:39:59   cp    -     10181423     554012
 ...
To list only snapshots(ss) use
-s
flag with lscp. See
lscp(1)
for all available options.
Converting checkpoints to snapshots
In order to recover data from checkpoint it first has to be converted into snapshot. To do that use
chcp
utility:
# chcp ss /dev/sdxY checkpoint-number
checkpoint-number
is number of the checkpoint listed in
lscp
in the CNO column.
lscp
will now show line like:
4  2025-04-14 22:28:56   ss    -     10181423     554012
To convert snapshot back to checkpoint use:
# chcp cp /dev/sdxY checkpoint-number
Creating snapshots
Use following to create a checkpoint:
# mkcp /dev/sdxY
Or to create a snapshot directly:
# mkcp --snapshot /dev/sdxY
Mounting snapshots
Following command will mount snapshot
checkpoint-number
read-only into
/mnt/snapshot
:
# mount -t nilfs2 -r -o cp=checkpoint-number /dev/sdxY /mnt/snapshot
Deleting snapshots
To delete a singular checkpoint use:
# rmcp /dev/sdxY checkpoint-number
To delete a range of checkpoints you can use:
# rmcp /dev/sdxY start..end
Where start is number of starting checkpoint and end the number of ending checkpoint.
To delete all checkpoints older than a checkpoint use:
# rmcp /dev/sdxY ..checkpoint-number
To delete all checkpoints newer than a checkpoint use:
# rmcp /dev/sdxY checkpoint-number..
Tip
Add -i flag to the rmcp for interactive use to double check inputted values
See
rmcp(8)
for further details.
Cleaning file system
To clear obsolete checkpoints from a mounted NILFS2 file system run:
# nilfs-clean /dev/sdxY
See
nilfs-clean(8)
and
nilfs_cleanerd(8)
for further details on garbage collector.
Resizing file system
nilfs-resize
tool resizes online NILFS2 file system.
Mounted NILFS2 filesystem can be resized with following command:
# nilfs-resize /dev/sdxY desired-size
Where
desired-size
can be suffixed by unit letter
s
,
K
,
M
,
G
, or
T
, for 512 byte sectors, kilobytes, megabytes, gigabytes, or terabytes, respectively. If
desired-size
is not specified, it will default to the size of partition.
nilfs-resize
does not change size of paritions themselves, they either have to be shrink afterwards when shrinking the filesystem or grown beforehand when enlarging it. This can be done with
fdisk
for example.
See
nilfs-resize(8)
for further details.
See also
NILFS2 FAQ