| DISKUTIL(8) | System Manager's Manual | DISKUTIL(8) |
diskutil — modify,
verify and repair local disks
diskutil |
[quiet] verb
[subVerb] [options] |
diskutil manipulates the structure of
local disks. It provides information about, and allows the administration
of, partitioning schemes, layouts, and formats of disks. This includes hard
disks, solid state disks, optical discs, disk images, APFS volumes,
CoreStorage volumes, and AppleRAID sets. It generally manipulates whole
volumes instead of individual files and directories.
Many diskutil commands, if improperly
used, can result in data loss. Most commands do not present confirmation
prompts. You should back up your data before using any of these
commands.
Each command verb is listed with its description and individual arguments.
-plist]internal | external]
[physical | virtual]
[device]
If no argument is given, then all whole disks and their partitions are listed.
You can limit the number of disks shown by specifying filtering arguments such as internal above, and/or a device disk. When limiting by a disk, you can specify either a whole disk, e.g. disk0, or any of its slices, e.g. disk0s3, but filtering is only done at the whole disk level (disk0s3 is a synonym for disk0 in this case).
If -plist is specified, then a property list will be emitted instead of the normal user-readable output.
A script could interpret the results of diskutil list -plist and use diskutil info -plist as well as diskutil listFilesystems -plist for more detailed information.
The top-to-bottom appearance of all whole disks is sorted in numerical order by unit (whole disk) number. However, within each whole disk's "sublist" of partitions, the ordering indicates actual on-disk location. The first disk item listed represents the partition which is located most near the beginning of its encompassing whole disk, and so on.
When viewed this way, the slice (partition) parts of the BSD disk identifiers may, in certain circumstances, not appear in numerical order. This is normal and is likely the result of a recent partition map editing operation in which volumes were kept mounted.
Note that both human-readable and plist output are sorted as described above.
See the DEVICES section below for the
various forms that the device specification may
take for this and all of the other diskutil
verbs.
This can be useful to watch system-wide activity of disks coming on-line or being ejected, volumes on disks being mounted or unmounted, volumes being renamed, etc. However, this output must never be parsed; programs should become Disk Arbitration clients instead.
For debugging information, such as the monitoring of applications dissenting (attempting to deny) activities for disks for which they have registered an interest, you must use the logging features of the diskarbitrationd daemon. Programs needing this information must become Disk Arbitration clients.
Up to a few seconds (or more) may be required for any Disk Arbitration dissenters in the system to approve the unmount, and/or for the file system to flush data. This verb gives up and returns failure after a maximum of 1 minute in most situations.
Force will force-unmount the volumes (less kind to any open files; see also umount (8)).
You should specify a whole disk, but all volumes of the whole disk are attempted to be unmounted even if you specify a partition.
If readOnly is specified, then the file system is mounted read-only, even if writing is supported or allowed by the volume's underlying file system, device, media, or user (e.g. the super-user). If nobrowse is specified, then the file system is mounted with a recommendation to prevent display (e.g. by the Finder) to the end user. These options are equivalent to passing rdonly or nobrowse as "-o" arguments to the appropriate file system bundle's mount (8) program. If -mountOptions is specified, then the argument strings you specify will be passed (by diskarbitrationd) verbatim to "-o"; multiple arguments must be separated with commas.
Up to a few seconds (or much longer in rare cases) may be required for any Disk Arbitration dissenters or disk claimers in the system to approve the mount, and/or for the file system to complete a minimal fsck(8). (For example, Disk Arbitration might invoke fsck_apfs -q before mounting an APFS Volume.) This verb gives up and returns failure after a maximum of 1 minute in most situations.
If -mountPoint is specified, then your path, rather than the standard path of /Volumes/VolumeName or /System/Volumes/VolumeName, will be used as the view into the volume file content; a directory at that path must already exist.
The journal for device will be moved externally onto the newly created Apple_Journal partition.
Since the journalDevice you specify will invariably be larger than 512MB, a new HFS+ partition will be created following the Apple_Journal partition to fill the remaining space.
Moving the journal works whether or not the volume is mounted, provided journaling is enabled on that volume. No errors are currently supported to flag attempts to move journals on volumes that do not have journaling enabled. If you have multiple volumes for which you want external journals, each must have its own external Apple_Journal partition. Ownership of the affected disks is required.
This setting for a particular volume is persistent across ejects and injects of that volume as seen by the current OS, even across reboots of that OS, because of the entries in this OS's Volume Database. Note thus that the setting is not kept on the target disk, nor is it in-memory.
For some locations of devices (e.g. internal hard disks), consideration of ownership settings on FSOs is the default. For others (e.g. plug-in USB disks), it is not.
When ownership is disabled, Owner and Group ID settings on FSOs appear to the user and programs as the current user and group instead of their actual on-disk settings, in order to make it easy to use a plug-in disk of which the user has physical possession.
When ownership is enabled, the Owner and Group ID settings that exist on the disk are taken into account for determining access, and exact settings are written to the disk as FSOs are created. A common reason for having to enable ownership is when a disk is to contain FSOs whose User and Group ID settings, and thus permissions behavior overall, is critically important, such as when the plug-in disk contains system files to be changed or added to.
See also the vsdbutil(8) command. Running as root is required.
This command will only run on a machine that contains exactly two internal disk devices: one solid-state device (SSD) and one rotational device (HDD), or, alternatively, two solid-state devices. This command must be able to make a positive identification thereof. If these requirements are met, you are prompted, and if you confirm, the erase and reset begins.
Both internal disk devices are (re)-partitioned with GPT maps, and then they are turned into (used to create) an APFS Fusion Drive Container with one APFS Volume.
All internal-disk data is lost. This includes any "extra" partitions (e.g. for Boot Camp or other "user" purposes). No system software is installed and no user data is restored. After running this command, you should (re)-install macOS on the machine (on the newly-created APFS Volume); otherwise, the machine will not be usable (bootable).
You generally must be booted from the Internet Recovery System (CMD-OPT-R) or from an externally-connected macOS boot disk (e.g. a USB drive), because you cannot erase a disk that hosts the currently-running macOS.
Externally-connected disk(s) are not affected. Ownership of the affected disks is required.
APM[Format] |
MBR[Format] | GPT[Format]]
device
If you specify Free Space for format, the partition itself is deleted (removed entirely) from the partition map instead of merely being erased. Ownership of the affected disk is required.
quick] device
force] [short]
device
If you desire a more sophisticated erase algorithm or if you need to erase only free space not in use for files, use the secureErase verb.
The force parameter causes best-effort, non-error-terminating, forced unmounts and shared-mode writes to be attempted; however, this is still no guarantee against drivers which claim the disk exclusively. In such cases, you may have to first unmount all overlying logical volumes (e.g. CoreStorage or AppleRAID). If a disk is partially damaged in just a certain unlucky way, you might even have to un-install a kext or erase the disk elsewhere.
The short parameter causes only a minimal amount of zeros to be written ("wipefs"); this is quick. You can use this to prevent inadvertent identification by software, e.g. as filesystem data.
Ownership of the affected disk is required.
freespace] level
device
Erasing a whole-disk will leave it useless until it is partitioned again. Erasing freespace on a volume will leave your files intact, indeed, from an end-user perspective, it will appear unchanged, with the exception that it will have attempted to make it impossible to recover deleted files.
If you need to erase all contents of a partition but not its hosting whole-disk, use the zeroDisk or randomDisk verbs. Ownership of the affected disk is required.
Level should be one of the following:
NOTE: This kind of secure erase is no longer considered safe. Modern devices have wear-leveling, block-sparing, and possibly-persistent cache hardware, which cannot be completely erased by these commands. The modern solution for quickly and securely erasing your data is encryption. Strongly-encrypted data can be instantly "erased" by destroying (or losing) the key (password), because this renders your data irretrievable in practical terms. Consider using APFS encryption (FileVault).
APM[Format] | MBR[Format]
| GPT[Format]] [part1Format
part1Name part1Size
part2Format part2Name
part2Size part3Format part3Name
part3Size ...]
(re)Partition a disk, removing all volumes. All volumes on
this disk will be destroyed. The device parameter
specifies which whole disk is to be partitioned. The optional
numberOfPartitions parameter specifies the number
of partitions to create; if given then the number of parameter triplets
(see below) is expected to match; else, the number of triplets alone
given will determine the number of partitions created.
If -noEFI is specified, do not create EFI partition
on the target disk.
The optional partitioning scheme parameter forces a particular partitioning scheme; if not specified, a suitable default is chosen. They are:
For each partition, a triplet of the desired file system format, volume name, and size must be specified. Several other diskutil verbs allow these triplets as well (and for them, the numberOfPartitions parameter is also optional). The triplets must be as follows:
Format guides diskutil both in what partition type to set for the partitions (slices) as well as what file system structures to initialize therein, using the file system bundle's plist's FormatExecutable setting which usually points to the appropriate formatter program such as newfs_hfs(8).
You can specify a format of Free Space to skip an area of the disk.
You can specify the partition type manually and directly with a format of %<human-readable partition type>% such as %Apple_HFS% or %<GPT partition type UUID constant>% such as %48465300-0000-11AA-AA11-00306543ECAC%; these imply a name of %noformat% (below). Human-readable types must be known to the system but UUID types (GPT scheme only) can be arbitrary.
If a name of %noformat% is specified, then the partition is left blank such that the partition space is carved out, the partition type is set according to the file system format name or explicit type, the partition space is partially erased ("wiped"), but a file system structure is not initialized with any file system's formatter program, e.g. newfs_hfs(8). This is useful for setting up partitions that will contain user-defined (not necessarily file system) data.
For a triplet whose format is Free Space or a directly-specified partition type, its name is ignored but a dummy name must nevertheless be present.
In addition to explicitly-requested partitions, space (gaps) might be allocated to satisfy certain filesystems' position and length alignment requirements; space might be allocated for possible future booter partition insertion; and indeed, actual booter partitions might be implicitly created.
In particular, there is a rule that unrecognized partitions 1GiB or larger automatically acquire booters. Thus, if you create an arbitrary partition with e.g. diskutil partitionDisk disk0 gpt %11112222-1111-2222-1111-111122221111% %noformat% 3gib jhfs+ Untitled r, then a booter partition will also be created. You can always delete that booter with diskutil eraseVolume "Free Space" dummy disk0s3.
The last partition is usually automatically lengthened to the end of the partition map (disk). You can specify an exact size for your last partition by specifying it as the penultimate triplet and specifying an additional (last) triplet as Free Space. Or you can use the R (remainder) size specifier for one of your middle partitions while specifying an exact size for your last partition.
Ownership of the affected disk is required.
Specifying limits instead of size takes no action, but instead prints the range of valid values for the target partition, taking into account current file system and partition map conditions such as files in use and other (immovable) partitions following the target.
Specifying mapsize instead of size takes no action, but instead prints the size of the encompassing whole-disk device, as well as the size of the entire partition map (all partitions less map overhead). The whole-disk device might be larger than the partition map if the whole-disk device has grown since the partition map was created. Growing a whole-disk device is possible with certain enterprise disk (RAID) systems.
The -plist option will print partition or whole-disk size inquiry information in property list format.
You can grow a volume (partition) (back) to its maximum size possible, provided no new partitions have been created that are in the way, by specifying R for the new volume size. You should use R instead of attempting an absolute value such as 100% because the latter cannot count partition map overhead.
When decreasing the size, new partitions may optionally be created to fill the newly-freed space. To do this, specify the numberOfPartitions, format, name, and size parameters in the same manner as the triplet description for the partitionDisk verb.
Resizing a volume that is currently set as the computer's startup disk will invalidate that setting; use the Startup Disk System Preferences panel or bless (8) to reset the resized volume as the startup disk.
Device refers to a volume; the volume's file system must be journaled HFS+. Valid sizes are a number followed by a capital letter multiplier or percent sign suffix as described in the SIZES section at the end of this page (e.g. 1.5T, 128M, 50%). Ownership of the affected disk is required.
For one of your triplets, you can optionally specify the R meta-size in lieu of a constant number value for the size parameter: the substituted value will be exactly the amount of space necessary to complete the re-filling of the original partition with all of your triplets.
Device refers to a volume. Ownership of the affected disk is required.
force] format
name fromDevice
toDevice
If force is not given, and the first partition has a resizable file system (e.g. JHFS+), the file system will be preserved and grown in a data-preserving manner; your format and name parameters are ignored in this case. If force is not given, and the first partition is not resizable, you are prompted if you want to format. You will also be prompted to format if the first partition has an (HFS) Allocation Block Size which is too small to support the required growth of the first partition; see the -b option for newfs_hfs (8).
If force is given, the final resulting partition is always (re)formatted. You should do this if you wish to (re)format to a new file system type. You will be prompted to confirm.
Format and name must always be given, but they have an effect only when force is given.
Merged partitions are required to be ordered sequentially on disk (see diskutil list for the actual on-disk ordering). All partitions in the range, except for the first one, must be unmountable. Ownership of the affected disk is required.
If device is a partition, then a new partition will be created in the gap that follows it, formatted with the file system personality format, with an initial volume name of name, extending for size, in the same manner as the triplet description for the partitionDisk verb.
If device is a (partition map-bearing) whole disk, then the new partition will automatically be placed last in the map.
Alternatively, you can create a new partition without any formatting by providing the partition type manually. To do so, pass a format parameter in the form of % followed by a raw GPT UUID or valid human-readable ioContent string followed by %, together with %noformat% for name. In this usage, any old on-disk data at the location of the new partition will be "wiped" (partially set to zeroes) to avoid any undesired interpretation.
You can request fit-to-fill by specifying a size of 0.
The partition map scheme must be GPT. A gap must exist at the target location, which will generally not be the case unless you have resized or deleted partitions. The partition map must contain at least one entry (the EFI partition suffices). Ownership of the affected disk is required.
While attached, the "handle" by which an APFS Container is identified is by its APFS Container Reference disk (device), e.g. "disk5" or "/dev/disk5". You should treat this as an opaque reference token.
The Container Reference disk is a synthesized whole-disk which is exported by APFS for identification purposes only; it has no storage. It is associated with the AppleAPFSContainerScheme node in the IO Registry. While APFS Volume device identifiers appear to be of a related form, you should never use the Container Reference as a basis to create device identifiers yourself; use the listing verbs with their plist options instead.
An APFS Container has a certain fixed size (capacity) which, via its Physical Store(s), uses physical space on a device. An APFS Container can be resized, but this is not a part of normal operation.
An APFS Physical Store disk is not necessarily a disk from a partition map; it could be e.g. an AppleRAID Set disk. Therefore, you must never assume that an APFS Physical Store's disk identifier is a 2-part form such as disk0s2.
An APFS Volume is identified by its device node, e.g. "disk5s1" or "/dev/disk5s1". The term volumeDevice is used below to refer to this device node.
APFS Volumes have no specified "size" (capacity). Instead, all APFS Volumes consume capacity out of the remaining free space of their parent APFS Container, consuming or returning such capacity as user file data is added or deleted. Note that this means that all Volumes within a Container compete for the Container's remaining capacity. However, you can manage Volume allocation with the optional reserve and quota size values.
The optional reserve size requests an assured minimum capacity for an APFS Volume. If successfully created, the Volume is guaranteed to be able to store at least this many bytes of user file data. Note that beyond this, the Volume might be able to store even more until constrained by reaching zero free space in its parent Container or by reaching a quota, if any. You can use a reserve to prevent running out of capacity due to competition from other Volumes or from a Container shrink attempt.
The optional quota size applies a maximum capacity to an APFS Volume, placing a limit on the number of bytes of user file data which can be stored on the Volume. Note that you might not be able to reach this limit if its parent Container becomes full first. You can use a quota to enforce accounting or to manage against "unfair" premature filling-up of the parent Container due solely to this Volume at the expense of sibling Volumes.
APFS Volumes can be tagged with zero or more role metadata flags which give a hint as to their intended use. Not all combinations of flags are valid, and not all flags are allowed to be set or changed by a user.
Efficient file copy cloning (copy-on-write) is supported; see copyfile(3) COPYFILE_CLONE.
Optional volume-level encryption is supported (see also Volume Groups below). An APFS Volume can be in an encrypted state because it was converted from a Core Storage encrypted volume, or because it was created as encrypted from its inception (e.g. with the diskutil apfs addVolume -passphrase verb) or because FileVault was enabled on it at some later time. On machines that support hardware encryption, the on-disk-device data for local volumes is encrypted even if FileVault is not enabled; this is termed "encrypted at rest".
The format of an APFS Volume's device identifier (volumeDevice) is that of a slice disk of a special whole-disk; both disks are synthesized by APFS. The "whole" identifier number (a positive possibly-multi-digit integer) is arbitrary, and the "slice" numbers (positive possibly-multi-digit integers) count up from 1 with each new Volume. Deleting Volumes may cause gaps in the numbering. This form appears the same as a partition (map) scheme and partitions, but it is completely unrelated. For example: If "disk3s2" is a Physical Store defining a Container, then "disk5s1", "disk5s2", and "disk5s3" might be the Container's Volumes; "disk5" exists but is never used directly.
Although it has a device node, an APFS Volume's data may only be accessed through its files; 3rd-party code cannot open an APFS Volume device node to "directly" access its on-disk bytes.
APFS Snapshots are normally not discoverable unless the "base" or one of the snapshots is mounted. APFS Snapshots are uniquely identified with a UUID (preferred) or within their parent Volume's namespace by either a numeric identifier or by their name; they can be renamed, but APFS will never allow duplication of names (within a Volume) to occur.
APFS Snapshots are mountable; when this occurs, its mount point (separate from and simultaneous with its parent Volume) provides a read-only historic version of the Volume content at Snapshot creation time.
You can revert the present state of an APFS Volume back to equality with a Snapshot in its history. This is a destructive reset/restore operation: Once a Volume is reverted, it cannot be brought forward. Any Snapshots between the revert point and the present are lost as well.
You can delete a Snapshot; this removes the possibility of ever reverting to that Snapshot's state, but does not affect the Volume's present-time content.
An APFS Snapshot mount point's "source device" (its statfs(2) f_mntfromname shown by the mount(8) command) is not necessarily a device node (e.g. disk0s2) as is common; it can be the Snapshot name followed by the '@' character and the "parent" Volume's device node, e.g. "SnapName123@/dev/disk2s1". See the mount_apfs(8) -s and fs_snapshot_create(2) commands. However, it is also possible for f_mntfromname to have a 3-part form ("diskCsVsS") if you are rooted (booted) from an APFS Snapshot; in this case, its "base" Volume (e.g. "diskCsV") will not be mounted.
APFS Volume Groups are identified using their Volume Group ID (a UUID). Assignment of this ID may be deferred in some cases.
A primary use for APFS Volume Groups is realization of macOS installations in which "System"-role (for the operating system) and "Data"-role (for user data) APFS Volumes are functionally linked (overlaid file namespace, crypto info), yet separated for reasons of security, backup, and software update.
Cryptographic identity, if any, is shared among all members of an APFS Volume Group.
APFS itself has no provision for backing up your data. Backups should be always be performed on a regular basis and before modifying any APFS Container using these commands.
The following is a list of APFS sub-verbs with their descriptions and individual arguments.
-plist]All currently-attached APFS Containers in the system are listed unless you specify a containerReferenceDevice, which limits the output to that specific APFS Container family.
If -plist is specified, then a property list will be emitted instead of the normal user-readable output.
-dryrun]
[-prebootSource
yourStagingDirectory]
[-noPrebootAdditions]
The source HFS volume can be located on a GPT partition or on an encrypted or non-encrypted, Fusion or non-Fusion CoreStorage logical volume (LV). In the latter case, the CoreStorage logical volume group (LVG) is dismantled, including automatic removal of any related Boot Camp Assistant partition(s).
If -dryrun is specified, all calculations, checks, and some data moving is performed, but your disk is left as valid HFS (headers remain declared as HFS, partition types are left alone, etc).
For volumes currently or planned to be macOS-bearing (and bootable), you can optionally specify -prebootSource with your own staging directory of macOS boot items; a Preboot Role APFS Volume with a UUID directory will automatically be created as part of the conversion process to facilitate macOS bootstrap. Normally your directory should be writable; additional (cryptographic and EFI rendering) items are automatically added to your directory prior to conversion and are not removed afterwards. You can opt-out of automatic item addition with the -noPrebootAdditions option.
Ownership of the affected disks is required.
Ownership of the affected disks is required.
For Fusion cases, if you do not explicitly use the -main and -secondary options, the performance duties are assigned automatically; this is preferred. Rotational vs. solid-state hardware design must be detectable; this is often not the case for external disks. Solid-state hardware is welcome but not required; it is the identification which holds as a hard requirement with this usage.
Alternatively, you can explicitly specify -main and -secondary devices; if you do so, you must specify both. The "main" device is assumed to be "faster" (you should use solid-state hardware if available), while the "secondary" device is assumed to be "slower" and is often used to store OS-associated "auxiliary" data such as a Boot Camp Assistant partition.
You cannot mix the use of disks from a disk image and not from a disk image.
After running this command, you may add APFS Volumes with the diskutil apfs addVolume verb; you must do this at least once in order to "use" the new Container.
Ownership of the affected disks is required.
You can identify the APFS Container by its Container Reference disk (preferred), or by one of its Physical Store disk(s).
The APFS Volumes are unmounted first; this process may not succeed if one or more is busy, in which case deleteContainer is aborted and all data is left intact (although some volumes might now be unmounted).
Otherwise, all APFS Volumes are deleted, their encryption-store entries are removed as applicable, the parent APFS Container is deleted, and the APFS Container's former Physical Store(s) are disposed of as follows:
If you did not specify a newName and all Physical Stores are partitions, then those partitions are deleted (turned into free space). You might then wish to use diskutil addPartition to re-purpose the newly-created gap in your partition map.
If you did specify a newName, or if one or more Physical Stores are whole disks (e.g. AppleRAID), then they are reformatted (as something other than APFS) with volume name(s) based on newName.
If you specified the triplet of newFormat newName newSize in the same manner as when using the partitionDisk verb, then they are each reformatted with the specified format and volume names based on newName. Only a newSize of 0 (fit-to-fill) is currently supported.
If your APFS Container is damaged, a Container Reference for it might not exist or it might not be functional. In this case, you can reclaim your former APFS Physical Store disk(s) by specifying the -force option; this activates an alternate last-resort mode. In this mode, if you had more than one Physical Store (e.g. the Fusion case) and the Container is sufficiently damaged, you might have to delete each Physical Store manually. You should normally avoid this mode.
Ownership of the affected disks is required.
If you specify an APFS Container Reference and that Container imports more than one Physical Store (in e.g. Fusion setups), the appropriate Physical Store will be chosen automatically.
Specifying limits instead of a size causes no action to be taken, but instead prints a range of valid values, taking into account various constraints; the -plist option will print this information in property list format.
Shrinks are constrained by the amount of data usage by all APFS Volumes on the targeted or implied APFS Container. Contributing to this data usage is the file content on the APFS Volumes, the existence of quotas and/or reserves, the usage of APFS Snapshots (e.g. by Time Machine), and metadata overhead.
Grows are constrained by the amount of partition map free space trailing the targeted or implied Physical Store partition.
When shrinking, new partitions may optionally be created to fill the newly-freed space. To do this, specify the format, name, and size parameters in the same manner as the triplet description for the partitionDisk verb.
You can specify a size of zero (0) to grow the targeted APFS Physical Store such that all remaining space is filled to the next partition or the end of the partition map.
Ownership of the affected disks is required, and all APFS Volumes on the Container must be unlocked.
The filesystem parameter sets the permanent APFS personality for this new APFS Volume; you should specify APFS or Case-sensitive APFS.
The new APFS Volume will be unencrypted unless you specify one of the passphrase options, in which case the volume will be encrypted from the beginning of its existence (as opposed to having encryption applied later); the user which is added will be the "Disk User". The optional passphraseHint is a user-defined string that can be displayed even while an encrypted APFS Volume is locked.
APFS Volumes have no fixed size; they allocate backing store on an as-needed basis. You can specify the reserve parameter to guarantee a minimum amount of space for your volume; at least that many bytes will be available for file data. You can also specify the quota parameter to limit your volume's file usage to a maximum amount; no more than that many bytes will be available for file data, even if there is otherwise enough space in the parent APFS Container. You can specify both reserve and quota simultaneously; however, the reserve is not allowed to be larger than the quota.
APFS Volumes can be tagged with certain role meta-data flags. You can supply the roles parameter with any combination of one or more of meta-data flags from APFS VOLUME ROLES section below or 0 as a no-op for scripting convenience. Note that you may be limited to only one role at a time and various other rules.
If you specify -groupWith, your new APFS Volume will become a member of the same APFS Volume Group as the APFS Volume groupDevice. If groupDevice is not yet associated with any group, such will be created automatically when appropriate.
The new APFS Volume is explicitly mounted after creation; you can specify -nomount to leave it unmounted, or, you can supply a "custom" mountpoint path, in which case you must be root, the directory must already exist, and you must delete the directory yourself when you unmount.
Ownership of the affected disks is required.
Ownership of the affected disks is required.
Removal will not start unless all Volumes in the Group can first be successfully unmounted.
Ownership of the parent APFS Container is required.
The "new" APFS Volume will inherit the APFS file system type (Case-sensitive or not) but will not inherit attributes such as name, reserve, quota, role, or encryption status.
The "new" APFS Volume will be unencrypted, unless you supply passphrase options in the same manner as diskutil apfs addVolume in which case it will be encrypted and initially accessible by the "Disk User".
The -role and -groupWith options function in the same manner as diskutil apfs addVolume.
If you need more control, you should delete and (re-)add the Volume instead.
Ownership of the affected disks is required.
The roles should be any combination of one or more of the role meta-data flags from APFS VOLUME ROLES section below. Unspecified flags are left alone, use of lower-case causes flags to be cleared, and use of upper-case causes flags to be set. Alternatively, clear will remove all flags, or 0 can be used as a no-op for scripting convenience. You should not make any assumptions about the usage or legal combinations of role flags.
Ownership of the affected disks is required.
If you do not supply the -user option, then all cryptographic users on that APFS Volume are searched for a match; if you supply -user disk then the Disk UUID (which equals the APFS Volume UUID) user is assumed; if you supply -user with a UUID then that specific user is assumed; if you instead supply -recoverykeychain then the Institutional Recovery user (see below) is assumed.
You will be prompted interactively for a passphrase unless you specify a passphrase parameter with -passphrase or pipe your passphrase into stdin and use -stdinpassphrase.
As an alternative to a passphrase, you can specify -recoverykeychain with a full path to a keychain file if an Institutional Recovery Key has been previously set up on the APFS Volume. The keychain must be unlocked; see security(1) and fdesetup(8) for more information.
This command will normally mount the APFS Volume after unlocking; if part of a Volume Group "System"/"Data"-role pair, both will be mounted. If (one of the) volume(s) is of the "System"-role, then it will be mounted as read-only unless you specify the -systemreadwrite option. You can skip the explicit mounting step with the -nomount option, or specify a "custom" mountpoint with the -mountpoint option. If you specify your own mountpoint path, it must exist and you must have write privileges on it (e.g. usually you must be root).
Specifying -verify will test passphrase correctness without affecting the locked or unlocked state.
If -plist is specified, then a property list will be emitted instead of the normal user-readable output; this list provides additional detail.
To re-lock the volume, unmount it, e.g. with diskutil unmount or diskutil apfs lockVolume.
Ownership of the affected disks is required.
Ownership of the affected disks is required.
The usual purpose of an APFS Cryptographic User is to authenticate for unlocking its APFS Volume; any of its users can do so.
An APFS Volume need not be encrypted in order to contain crypto users; indeed, other than the Disk User, they should be added before encrypting.
Types of Cryptographic Users include the at-most-one-per-Volume "Disk" user, whose UUID value always matches its Volume's UUID; iCloud or personal "Recovery Keys", which are not users per se, but instead store partial crypto keys and are paired with corresponding "Recovery Users" and have fixed-constant UUID values; and, most commonly, "Open Directory" users, whose UUID values match corresponding local macOS Open Directory (OD) account user GUIDs (e.g. the common local user accounts; see dscl(1) for more information).
If -plist is specified, then a property list will be emitted instead of the normal user-readable output.
The old and new passphrases are specified in the same manner as diskutil apfs addVolume; you will be interactively prompted as necessary if you do not specify both.
Ownership of the affected disks is required.
Ownership of the affected disks is required.
You can supply an existing cryptographic user UUID, in which case you must supply its corresponding passphrase, or you can supply disk (or the Disk/Volume UUID) and the corresponding passphrase of the "Disk User", provided the "Disk User" already exists.
Alternatively, if no users exist yet on this APFS Volume, you can still supply disk (or the Disk/Volume UUID), and a "Disk User" will be created with a new passphrase which you supply. This is the only way using diskutil in which an APFS Volume that has no cryptographics users on it yet can acquire the first such user.
The passphrase, interactive or not, is specified in the same manner as diskutil apfs addVolume.
Ownership of the affected disks is required.
The APFS Volume must be in an unlocked state before invoking this operation. Additionally, this operation itself requires that you authenticate.
Any existing cryptographic user and its passphrase on the APFS Volume can be supplied, using -user with either a UUID or the word disk to specify the "Disk User". If a "Disk User" exists on the APFS Volume and you omit the -user parameter, then the "Disk User" is assumed.
As an alternative to a passphrase, you can specify -recoverykeychain with a full path, in the same fashion as the unlockVolume verb.
If you do not supply a passphrase, yet one is required, you will be prompted interactively by cryptographic user UUID.
Ownership of the affected disks is required.
If you are rooted (booted) from an APFS Snapshot, you can specify the appropriate 3-part BSD identifier (e.g. "disk1s2s1").
If -plist is specified, then a property list will be emitted instead of the normal user-readable output.
Snapshot removal proceeds in the background and might not be finished when this command exits unless you specify -wait.
Ownership of the affected disks is required.
If -plist is specified, then a property list will be emitted instead of the normal user-readable output.
Ownership of the affected disks is required.
MacOS user metadata is sourced from macOS and Open Directory (OD) database files that are searched for on the given volumeDevice, which is normally expected to be a macOS installation.
You can use a different Open Directory database by supplying the -od option with a full path, e.g. "/Volumes/SomeOtherMacOSVolume/var/db/dslocal/nodes/Default", or with / to use the currently-running macOS (even if volumeDevice is not). Redirecting the database source can lead to loss of access; it must never be done unless you have a precise reason.
If some user cannot log in or login metadata is out of date, diskutil apfs updatePreboot / can be used as a repair.
You should normally never have to use this verb; the Preboot Volume is updated automatically when you use Users & Groups in System Preferences.
Ownership of the affected disks is required.
You must never use this command unless you know precisely why you are doing so.
Ownership of the affected disks is required.
Of these three basic types, only the "mirror" type increases fault-tolerance. Mirrors may have more than two disks to further increase their fault-tolerance. Striped and concatentated volumes are, in fact, more vulnerable to faults than single disk volumes.
From these basic types, "stacked" or "nested" RAID volumes can be created. Stacked RAID sets that make use of mirrored RAID sets are fault-tolerant. For example, these are some of the more common combinations of stacked RAID sets:
When creating new RAID sets or adding disks, if possible, it is better to specify the entire disk instead of a partition on that disk. This allows the software to reformat the entire disk using the most current partition layouts. When using whole disks, the type of partitioning used is selected based on the platform type (PPC = APMFormat, Intel = GPTFormat). GPT and APM partition formats cannot be mixed in the same RAID set.
In addition to whole disk and partition device names, AppleRAID uses UUIDs to refer to existing RAID sets and their members. Existing RAID sets may also be specified by mount point (e.g. /Volume/raidset). In many cases, using the UUID for the device argument is preferred because disk device names may change over time when disks are added, disks are removed or when the system is rebooted. If RAID members have been physically disconnected from the system or are no longer responding, you must use the member's UUID as the command argument. Messages in the system log will refer to RAID sets and their member disks by UUID. For more information on specifying device arguments, see the DEVICES section below.
AppleRAID is not a replacement for backing up your data. Backups should be always be performed on a regular basis and before modifying any RAID set using these commands.
The following is a list of appleRAID sub-verbs with their descriptions and individual arguments.
-plist | UUID]mirror | stripe |
concatmirror | concatOwnership of the affected disk is required. diskutil updateRAID is a deprecated synonym for diskutil appleRAID update.
CoreStorage maintains a world of virtual disks, somewhat like RAID, in which one can easily add or remove imported backing store disks, as well as exported usable volumes, to or from a pool (or several pools). This provides the user with flexibility in allocating their hardware; user or operating system data can span multiple physical disks seamlessly, for example.
CoreStorage is deprecated in favor of Apple APFS.
Apple CoreStorage defines four types of objects, instances of which are uniquely represented by a UUID:
The Logical Volume Group (LVG) is the top or "pool" level; zero or more may exist during any OS boot time session.
An LVG imports one or more Physical Volumes (PVs). A PV represents a device that feeds the LVG storage space; a PV is normally real media but it can be a disk image or even an AppleRAID Set. A disk offered to be a PV must be a partition and the encompassing scheme must be GPT.
An LVG exports zero or more Logical Volume Families (LVFs). An LVF contains properties which govern and bind together all of its descendant Logical Volumes (LVs). These properties provide settings for Full Disk Encryption (FDE) (such as whether the LVs are encrypted, which users have access, etc) and other services. However, at the present time, for the creation of any new LVFs, only zero or one LVF per LVG is supported.
A Logical Volume Family (LVF) exports one or more Logical Volumes (LVs). However, only and exactly one LV per LVF is supported.
A Logical Volume (LV) exports a dev node, upon which a file system (such as Journaled HFS+) resides.
For more information on specifying device arguments, see the DEVICES section below.
The following is a list of coreStorage sub-verbs with their descriptions and individual arguments.
-plist | UUID]-plist] UUID |
device
-nomount] lvUUID
[-stdinpassphrase] |
[-passphrase passphrase]
| [-recoverykeychain
file]
If no -passphrase option is specified, you will be prompted interactively; else, your passphrase is used. Or, if you specify -stdinpassphrase then the standard input is read (e.g. so that the passphrase can be securely piped in without having to expose it).
Alternatively, you can specify -recoverykeychain with a path to a keychain file. The keychain must be unlocked; see security(1) for more information.
The locked state means that the CoreStorage driver has not been given authentication information (a passphrase) to interpret the encrypted bytes on disk and thus export a dev node. This verb unlocks a logical volume family (LVF) and its logical volumes (LVs) by providing that authentication; as the LVs thus appear as dev nodes, any file systems upon them are automatically mounted unless the -nomount option is given.
To re-lock the volume, make it offline again by ejecting it, e.g. with diskutil eject.
Add verbose flag for verbose output.
Add plist flag for the diskimageverb to produce output in a plist format. Intended for other programs to use this flag in order to consume the output instead of attempting to parse human-readable text.
Add stdinpassphrase to read the passphrase from stdin instead of prompting for one.
The following is a list of diskutil image sub-verbs with their descriptions and individual arguments.
image-url can be one of:
If readOnly is specified, then the disk image is attached read-only, even if writing is supported or allowed by the volume's underlying file system, device, media, or user (e.g. the super-user).
Mount Policy:
Can be one of: noMount, autoMount, forceMount.
By default, will attempt to mount the disk image after attaching it (unless it is a ram disk), in case of no mountable filesystem on the image, the operation will fail ( forceMount ). Specifying noMount flag will skip any mount attempts and only attach the disk image. Lastly, autoMount will attempt to perform a mount after successful attach. In case no mountable filesystem is present the operation will end successfully.
noMount flag behaves the same as specifying mountPolicy=noMount. Note that you cannot specify this flag with conflicting mount policies.
Mount only related options (cannot be used with noMount ):
In case mountPoint is supplied, then it will be used as the path to view into the volume; a directory at the supplied path must already exist. Note, that when specifying this option, the disk image should contain only a single mountable entity, otherwise the operation will fail. Additionally, can manipulate the mount operation by passing mountOptions, see mount(8). Can supply multiple options separated by ','. These options will be used during mount operation. Lastly, nobrowse can be supplied to hide the mounted volume in the disk image from GUI applications (such as Finder).
Creates an optionally encrypted disk image.
With encrypt can encrypt the newly created disk image using AES-256. When creating from source and encryption applies to both, source and destination, stdinpassphrase applies the first passphrase to source and the second to destination.
At the end of the operation the image is not mounted.
Use blank to create a blank disk image. Use from to create the disk image from source (e.g. disk3 / existing disk image).
The disk image will be created at image-path. Should be a writable path.
format
name creates an APFS filesystem with the requested volume name on the image (default: untitled).
size allows to specify the size of the newly created image, see SIZES.
The disk image will be created at image-path. Should be a writable path.
format
source should be the source for the disk image to be created from (e.g. disk3 / existing disk image).
In case the image contains a resizable filesystem (e.g. APFS) it will be resized and image limits will be calculated accordingly.
In case the image contains one or more partitions, only the last one will be resized based on the input.
Only GPT partition tables are supported or partition-less images with APFS.
The image should not be attached prior to resizing.
size The new size of the disk image, should not exceed the size from the disk image limits. Can be either size from size section (see SIZES) or 'min' to resize to minimum size as reported by diskutil.
image-only Will only resize the disk image and adjust a secondary GPT table to the new size if there is one.
A device parameter for any of the above commands (except where explicitly required otherwise) can usually be any of the following:
The (BSD) disk identifier string variously identifies a physical or logical device unit, a session (if any) upon that device, a partition (slice) upon that session (if any), a virtual logical volume, or a moment in a volume's evolution. It may take the form of diskU, diskUsP, diskUsQ, diskUsQsP, diskC, diskCsV, or diskCsVsS where C, P, Q, S, U, and V are positive decimal integers (possibly multi-digit), and where:
Some units (e.g. floppy disks, RAID sets) contain file system data upon their "whole" device instead of containing a partitioning scheme with partitions.
Note that some of the forms appear the same and must be distinguished by context. For example, diskUsQ, diskUsS, and diskCsV are all 2-part forms that can mean different things: For non-optical media, it identifies a partition (on a partition map) upon which (file system) data is stored; for optical media, it identifies a session upon which an entire partition map (with its partitions with file systems) is stored; for an APFS setup, it identifies an APFS Volume. As another example, in "stacked" cases (CoreStorage on AppleRAID or APFS on AppleRAID), the 1-part diskU form becomes a CoreStorage PV or APFS PhysicalStore, in contrast with the more-common 2-part form.
It is important for software to avoid relying on numerical ordering of any of the parts. Activities including but not limited to partition deletions and insertions, partition resizing, virtual volume deletions and additions, device ejects and attachments due to media insertion cycles, plug cycles, authentication lock cycles or reboots, can all cause (temporary) gaps and non-increments in the numerical ordering of any of the parts. You must rely on more persistent means of identification, such as the various UUIDs.
Wherever a size is emitted as an output, it is presented as a base-ten approximation to the precision of one fractional decimal digit and a base-ten SI multiplier, often accompanied by a precise count in bytes. Scripts should refrain from parsing this human-readable output and use the -plist option instead.
Wherever a size is to be supplied by you as an input, you can provide values in a number of different ways, some absolute and some context-sensitive. Values are interpreted as base ten and must be positive with no preceding "+". An integer without a suffix is taken to mean an exact number of bytes (e.g. 5368709120). Multiplier suffixes are optional, must follow your value immediately without whitespace, and allow your value to be a real number (e.g. 5.1234t). Some of the specifiers below should not have a preceding value at all (e.g. the letter R for "remainder").
Power-of-ten suffixes:
Power-of-two suffixes:
The following are useful when working with devices and partition maps:
In certain contexts (e.g. when asking to "use all space available", or when building partition triplets) you can provide a relative value as follows:
You can provide an operating system-defined constant value as follows:
Note again that B refers to bytes and S and UAM refer to a constant multiplier of 512; the latter are useful when working with tools such as gpt (8) or df (1). Note also that this multiplier is not a "block" size as actually implemented by the underlying device driver and/or hardware, nor is it an "allocation block", which is a file system's minimum unit of backing store usage, often formatting-option-dependent.
Examples: 10G (10 gigabytes), 4.23tb (4.23 terabytes), 5M (5 megabytes), 4GiB (exactly 2^32 bytes), 126000 (exactly 126000 bytes), 25.4% (25.4 percent of whole disk size).
The format parameter for the erasing and partitioning verbs is the file system personality name. You can determine this name by looking in a file system bundle's /System/Library/Filesystems/<fs>.fs/Contents/Info.plist and looking at the keys for the FSPersonalities dictionary, or by using the listFilesystems verb, which also lists shortcut aliases for common personalities (these shortcuts are defined by diskutil for use with it only).
Common examples include JHFS+, JHFSX, MS-DOS, etc, as nicknames for the canonical forms from the file system bundles such as "Case-sensitive HFS+".
APFS Volumes can be tagged with certain role meta-data flags. Supported flags are:
Erase a whole disk (device)
diskutil eraseDisk JHFS+ Untitled disk3
Erase a volume (or format a partition or virtual disk)
diskutil eraseVolume jhfs+ UntitledHFS /Volumes/SomeDisk
Erase and (re)-partition a disk (device) with three partitions
diskutil partitionDisk disk3 HFSX Foo1 10G JHFS+ Foo2 10G MS-DOS FOO3 0
Erase and format with a different volume file system
diskutil eraseVolume ExFAT FOO disk3s2
Remove a partition from a partition map (results in free space)
diskutil eraseVolume free free disk3s2
Add a new partition to a partition map (into free space)
diskutil addPartition disk3s2 ExFat FOO 0
diskutil addPartition disk3s2 %Apple_HFS% %noformat% 2.5g
diskutil addPartition disk3 ExFat FOO 50%
Convert a HFS disk to APFS
diskutil apfs convert disk3s2
Create a new APFS Container with three new APFS Volumes
diskutil apfs createContainer disk0s2
diskutil apfs addVolume disk8 APFS MyVolume1
diskutil apfs addVolume disk8 APFS MyVolume2 -passprompt
diskutil apfs addVolume disk8 APFS MyVolume3 -quota 10g
diskutil apfs list
Encrypt an APFS Volume (enable FileVault)
diskutil apfs encryptVolume disk8s1 -user disk
Lock or unlock an APFS Volume
diskutil apfs list disk8
diskutil apfs lockVolume disk8s1
diskutil apfs unlockVolume disk8s1 (tries all users)
diskutil apfs unlockVolume disk8s2 -user USERUUID (tries
specific user)
Decrypt an APFS Volume (disable FileVault)
diskutil apfs listUsers disk8s1
diskutil apfs decryptVolume disk8s1 -user USERUUID
Remove an APFS Volume from its APFS Container altogether
diskutil apfs deleteVolume disk8s3
Resize an HFS volume and create a volume after it
diskutil resizeVolume /Volumes/SomeDisk 50g MS-DOS DOS 0
Resize an HFS volume and leave all remaining space as unused
diskutil resizeVolume /Volumes/SomeDisk 12g
Merge two partitions into a new partition
diskutil mergePartitions JHFS+ not disk1s3 disk1s5
Split a partition into three new ones
diskutil splitPartition /Volumes/SomeDisk JHFS+ vol1 12g MS-DOS VOL2 8g JHFS+
vol3 0
Create an AppleRAID
diskutil createRAID mirror MirroredVolume JHFS+ disk1 disk2
Destroy an AppleRAID
diskutil destroyRAID /Volumes/MirroredVolume
Repair a damaged AppleRAID
diskutil repairMirror /Volumes/MirroredVolume disk3
Convert volume into an AppleRAID volume
diskutil enableRAID mirror /Volumes/ExistingVolume
Erase a partition, shrink, associate a pre-macOS-13.0 Recovery
Partition
diskutil splitPartition disk8s2 JHFS+ MacHD R %Apple_Boot% %noformat%
%recovery%
Partition a disk with the MBR partitioning scheme (e.g. for a
camera)
diskutil partitionDisk disk3 MBR MS-DOS CAM1 0
Partition a disk with the (deprecated) APM partitioning scheme
diskutil partitionDisk disk3 APM HFS+ vol1 15% Journaled\ HFS+ vol2 R
Journaled\ HFS+ vol3 25% Free\ Space volX 10g
Attach a 100MiB RAM disk image
diskutil image attach --mountPolicy=noMount ram://100MiB
Attach a read-only disk image at some specified mount point
diskutil image attach --readOnly --mountPoint /tmp/myMountPoint
/tmp/myImage.dmg
Creating a blank 100MiB disk image with UDSB format
diskutil image create -s 100MiB -f UDSB /tmp/myImage.dmg
Creating a blank 100MiB disk image with APFS volume named MyVolume
diskutil image create -s 100MiB --volumeName MyVolume /tmp/myImage.dmg
Creating a disk image from an existing disk
diskutil image create from --source disk3 /tmp/myImage.dmg
Resizing a disk image:
diskutil image resize --size 100G /tmp/my.dmg
Resize to minimal size:
diskutil image resize --size min /tmp/my.dmg
Print resize limits in plist format
diskutil image resize --plist /tmp/my.dmg
diskutil will exit with status based on sysexits (see sysexits(3)) or 1 if it cannot complete the requested operation; this includes cases in which usage text is printed. Before diskutil returns with non EX_OK status, it prints a message which might include an explanation local to diskutil, an error string from the DiskManagement or MediaKit frameworks, an underlying POSIX error, or some combination.
authopen(1), drutil(1), hdiutil(1), apfs.util(8), corestoraged(8), diskarbitrationd(8), diskmanagementd(8), diskmanagementstartup(8), fdesetup(8), fsck_apfs(8), fsck_hfs(8), hfs.util(8), ioreg(8), mount(8), mount_apfs(8), msdos.util(8), newfs_apfs(8), newfs_hfs(8), sysexits(3), ufs.util(8), umount(8), vsdbutil(8)
The eraseDisk and partitionDisk verbs had an option to add Mac OS 9 drivers (in partitions designated for that purpose); there was also a repairOS9Permissions verb. These have been removed.
Starting with Mac OS X 10.6, the input and output notation of disk and partition sizes use power-of-10 suffixes. In the past this had been power-of-2, regardless of the suffix (e.g. G, Gi, GiB) used for display or accepted as input. Starting with Mac OS X 10.11, the B suffix is optional even for "bare" numeric values.
Starting with Mac OS X 10.11, the verify- and repairPermissions verbs have been removed.
Starting with macOS 10.12, the plist output of partitions from diskutil list -plist is presented in on-disk (not BSD slice name, e.g. disk0s2) order. This mimics the order of outputs from programs such as gpt (1). The human-readable output always has been, and remains, in on-disk order.
Starting with macOS 10.13.2, APFS cryptographic user authentication is required even when disabling FileVault.
Starting with macOS 10.14, partitions on all media above 1GiB in size will default to 1MiB alignment, regardless of the partitioning scheme. This is significant for MBR partition maps and their use in appliances such as cameras. Free-space requests will not be aligned.
Starting with macOS 11.0, certain Core Storage manipulation verbs have been removed.
| 27 October 2021 | macOS |