Get mkfs.xfs wrong and you overwrite the wrong disk in one command with no undo. This guide gets you to a formatted, labelled, mounted XFS filesystem with a verification check at the end, so you know it actually worked before you trust it. The examples match mkfs.xfs from xfsprogs 6.6.0, package version 6.6.0-1ubuntu2.1.
Allow about 15 minutes for a new, empty device, plus time to check its identity. You need the xfsprogs package, a target block device or logical volume, and root privileges for the formatting and mounting commands.
Use stable device information before writing anything. Replace the placeholder with the device you intend to format:
target=/dev/EXAMPLE_DATA_DEVICE
lsblk -o NAME,PATH,SIZE,TYPE,FSTYPE,LABEL,MOUNTPOINTS "$target"
findmnt --source "$target"The first command should show the expected size and type. The second should produce no filesystem row when the device is not mounted. If it is mounted, stop the services using it and then unmount as an elevated operation:
sudo umount "$target"If findmnt still reports a mount, do not format yet. Find the owning service or process and decide whether stopping it is safe. Formatting a mounted or actively used device can corrupt unrelated data and disrupt a service.
Checkpoint: Write down the exact path, size and serial or WWN shown by your storage tooling. A path such as /dev/sdb can refer to a different disk after a reboot or hardware change.
Run the same command with -N first. This prints the parameters without creating the filesystem:
sudo mkfs.xfs -N -L archive "$target"Check the output against what you expect: the target device, the size, an internal log, and the label archive. The default block size is 4 KiB and the default sector size is 512 bytes. Metadata CRCs are on by default in this release, and the command tests the CRC32c implementation before a real format, so a failed test aborts formatting before it touches the disk.
Do not add -f merely to silence a warning. By default, mkfs.xfs refuses to write when it detects an existing filesystem or partition table. That refusal is a useful safety boundary, not an obstacle.
Only continue when the preview and device identity agree. This is destructive and needs elevated privileges:
sudo mkfs.xfs -L archive "$target"A normal run prints the geometry and feature choices it is about to create, then writes the XFS metadata. The label is limited to 12 characters. Size suffixes such as k, m and g are binary multiples, so 100m means 100 MiB, not 100,000,000 bytes.
For a separate log device, both devices must be deliberately selected and prepared for that layout. This form creates the data filesystem on one device and a 100 MiB log on another:
sudo mkfs.xfs -L archive -l logdev=/dev/EXAMPLE_LOG_DEVICE,size=100m "$target"Do not use that form unless the log device is the correct dedicated device: the data device and log device must never be confused, and the log must be at least 64 MiB and no larger than 2 GiB.
If the command refuses because it found an existing filesystem or partition table, stop and investigate before you force anything. The force option is explicit:
sudo mkfs.xfs -f -L archive "$target"Warning: -f permits overwriting the detected content. It is not an undo switch. Recovery then depends on backups or specialist data recovery, and may not be possible at all.
Create a mount point and mount the new filesystem. These change system state and need root:
sudo install -d -m 0755 /srv/archive
sudo mount "$target" /srv/archive
findmnt --source "$target" -o SOURCE,FSTYPE,LABEL,OPTIONS,TARGET
df -hT /srv/archiveExpect xfs as the filesystem type, archive as the label, and /srv/archive as the target from findmnt. Options and capacity vary with the device and kernel. If mounting fails, do not reach straight for a reformat: check journalctl -k -n 50 and confirm the device path, filesystem type and kernel support are all correct.
Prove the mounted filesystem accepts a file, then remove only that test file:
sudo sh -c 'printf "%s\n" "mkfs.xfs verification" > /srv/archive/.mkfs-xfs-test'
sudo test -s /srv/archive/.mkfs-xfs-test
sudo rm /srv/archive/.mkfs-xfs-testFor a temporary mount used only during testing, undo it with:
sudo umount /srv/archiveUnmounting does not erase the filesystem, it just detaches it from that directory. To make it survive a reboot, add a carefully checked entry to /etc/fstab, preferably using the UUID from blkid "$target", then test with sudo mount -a before you trust it. Review that file before saving: a bad entry can delay or prevent a normal boot.
-b size= changes the fundamental block size. This affects compatibility and must not exceed the Linux page size for a filesystem Linux will mount.-s size= changes the sector size. Must be a power of two no larger than the filesystem block size.-c options=PATH loads a configuration file using INI-style sections such as [block], [metadata] and [inode]. Command-line and configuration options combine, and a duplicate between them is an error. Not every command-line option is valid inside one of these files, so preview with -N before formatting for real.-q suppresses the geometry output. Only use it when another tool captures the result; it makes an accidental target harder to spot.-K prevents discard operations during formatting. Only use it when you have a specific reason to.Most installations should just start with the defaults. Keep a configuration file beside your deployment documentation if you use one.
mkfs.xfs -N showed the intended geometry and label.findmnt reports the expected XFS label and mount point./etc/fstab change uses a verified UUID and passes sudo mount -a.