DISKUTIL(8) BSD System Manager’s Manual DISKUTIL(8) NAME
diskutil -- modify, verify and repair local disks
SYNOPSIS
diskutil [quiet] verb [options]
DESCRIPTION
diskutil manipulates the structure of local disks. It
provides informa-
tion about, and allows the administration of, partitioning
schemes, lay-
outs, 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
indi-
vidual files and directories.
CAUTION
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.
VERBS
Each command verb is listed with its description and
individual argu-
ments.
list [-plist] [internal | external] [physical | virtual] [device]
List disks, including internal and external disks,
whole disks
and partitions, and various kinds of virtual or offline
disks.
If no argument is given, then all whole disks and their
parti-
tions are listed.
You can limit the number of disks shown by specifying
filter-
ing 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
indi-
cates actual on-disk location. The first disk item
listed rep-
resents 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.
info | information [-plist] device | -all
Get detailed information about a specific whole disk or
parti-
tion. If -plist is specified, then a property list
instead of
the normal user-readable output will be emitted. If
-all is
specified, then all disks (whole disks and their
partitions)
are processed.
activity
Continuously display system-wide disk manipulation
activity as
reported by the Disk Arbitration framework until
interrupted
with a signal (e.g. by typing Control-C).
This can be useful to watch system-wide activity of
disks com-
ing on-line or being ejected, volumes on disks being
mounted
or unmounted, volumes being renamed, etc. However,
this out-
put must never be parsed; programs should become Disk
Arbitra-
tion clients instead.
For debugging information, such as the monitoring of
applica-
tions dissenting (attempting to deny) activities for
disks for
which they have registered an interest, you must use
the log-
ging features of the diskarbitrationd daemon. Programs
needing
this information must become Disk Arbitration clients.
listFilesystems [-plist]
Show the file system personalities available for
formatting in
diskutil when using the erasing and partitioning verbs.
This
is a subset of the complete set of personalities
exported by
the various file system bundles that may be installed
in the
system. Also shown are some shortcut aliases for
common per-
sonalities. See the FORMAT section below for more
details.
If -plist is specified, then a property list instead of
the
normal user-readable output will be emitted.
unmount | umount [force] device
Unmount a single volume. Force will force-unmount the
volume
(less kind to any open files; see also umount (8)).
unmountDisk | umountDisk [force] device
Given a disk containing a partition map, unmount all of
its
volumes. That is, unmounts are attempted for the map's
parti-
tions containing file system volumes, as well as for
"virtual"
volumes exported by storage systems which import data
from the
map's partitions. Storage systems supported include
APFS,
AppleRAID, and CoreStorage.
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 par-
tition.
eject device
Eject a disk. Media will become offline for the
purposes of
being a data store for file systems or being a member
of con-
structs such as software RAID or direct data.
Additionally,
removable media will become eligible for safe manual
removal;
automatically-removable media will begin its physical
(motor-
ized) eject sequence.
mount [readOnly] [nobrowse] [-mountOptions option [, option]]
[-mountPoint path] device
Mount a single volume.
If readOnly is specified, then the file system is
mounted
read-only, even if writing is supported or allowed by
the vol-
ume'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
appropri-
ate 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
argu-
ments must be separated with commas.
If -mountPoint is specified, then your path, rather
than the
standard path of /Volumes/VolumeName or
/System/Volumes/Volu-
meName, will be used as the view into the volume file
content;
a directory at that path must already exist.
mountDisk device
Mount all mountable and UI-browsable volumes on the
given par-
tition map; that is, a mount is attempted on the
directly-
mountable volume, if any, on each of the whole disk's
parti-
tions. However, "virtual" volumes, such as those are
implied
by e.g. Core Storage Physical Volumes, AppleRAID
Members,
etc., are not handled. You should specify a whole
disk, but
all volumes of the whole disk are attempted to be
mounted even
if you specify a partition.
rename | renameVolume device name
Rename a volume. Volume names are subject to file
system-spe-
cific alphabet and length restrictions.
enableJournal device
Enable journaling on an HFS+ volume. This works
whether or
not the volume is currently mounted (the volume is
temporarily
mounted if necessary). Ownership of the affected disk
is
required.
disableJournal [force] device
Disable journaling on an HFS+ volume. This normally
works
whether or not the volume is currently mounted (the
volume is
temporarily mounted if necessary). If the force option
is
specified, then journaling is disabled directly on
disk; in
this case, the volume must not be mounted. Ownership
of the
affected disk is required.
moveJournal external journalDevice device
Create a 512MB Apple_Journal partition using the
journalDevice
partition to serve as a journal for the volume device.
For
best results, journalDevice should be a partition on a
differ-
ent whole-disk than the volume itself.
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 vol-
umes that do not have journaling enabled. If you have
multi-
ple volumes for which you want external journals, each
must
have its own external Apple_Journal partition.
Ownership of
the affected disks is required.
moveJournal internal device
Move the journal for device back locally (onto that
same
device). Ownership of the affected disk is required.
enableOwnership device
Enable ownership of a volume. The on-root-disk Volume
Data-
base at /var/db/volinfo.database is manipulated such
that the
User and Group ID settings of files, directories, and
links
(file system objects, or "FSOs") on the target volume
are
taken into account.
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), con-
sideration 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 phys-
ical 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
set-
tings, 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.
disableOwnership device
Disable ownership of a volume. See enableOwnership
above.
Running as root is required.
verifyVolume device
Verify the file system data structures of a volume.
The
appropriate fsck program is executed and the volume is
attempted to be left mounted or unmounted as it was
before the
command. Any underlying Storage System (e.g. Core
Storage,
APFS) is verified before the target volume itself. In
certain
cases, "live" verify, including of the boot volume, is
sup-
ported. Ownership of the disk to be verified is
required.
repairVolume device
Repair the file system data structures of a volume.
The
appropriate fsck program is executed and the volume is
attempted to be left mounted or unmounted as it was
before the
command. Any underlying Storage System (e.g. Core
Storage,
APFS) is repaired before the given target volume. In
most
cases (e.g. except mount-read-only), the target volume
must be
unmountable; in all cases, the underlying storage media
must
be writable. "Live" repair (e.g. of a file-writable
mounted
volume) is not supported. Ownership of the affected
disk is
required.
verifyDisk device
Verify the partition map layout of a whole disk
intended for
booting or data use on a Macintosh. The checks further
include, but are not limited to, the integrity of the
EFI Sys-
tem Partition, the integrity of any Core Storage
Physical Vol-
ume partitions, and provisioning of space for boot
loaders.
Ownership of the disk to be verified is required; it
must be a
whole disk and must have a partition map.
repairDisk device
Repair the partition map layout of a whole disk
intended for
booting or data use on a Macintosh. The repairs
further
include, but are not limited to, the repair or creation
of an
EFI System Partition, the integrity of any Core Storage
Physi-
cal Volume partitions, and the provisioning of space
for boot
loaders. Ownership of the affected disk is required;
it must
be a whole disk and must have a partition map.
resetFusion
For Fusion Drive machines (two internal disk device
hardware
configurations), reset the disk devices in the machine
to the
factory-like state of one empty Fusion volume.
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" par-
titions (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.
eraseDisk format name [APM[Format] | MBR[Format] | GPT[Format]]
device
Erase an existing disk, removing all volumes and
writing out a
new partitioning scheme containing one new empty file
system
volume. If the partitioning scheme is not specified,
then an
appropriate one for the current machine is chosen.
Format is
discussed below in the section for the partitionDisk
verb.
Ownership of the affected disk is required.
eraseVolume format name device
Write out a new empty file system volume (erasing any
current
file system volume) on an existing partition. The
partition
remains but its data is lost. Format is discussed
below in
the section for the partitionDisk verb.
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.
reformat device
Erase an existing volume by writing out a new empty
file sys-
tem of the same personality (type) and with the same
volume
name. Ownership of the affected disk is required.
eraseOptical [quick] device
Erase optical media (CD/RW, DVD/RW, etc.). Quick
specifies
whether the disc recording system software should do a
full
erase or a quick erase. Ownership of the affected disk
is
required.
zeroDisk [force] [short] device
Erase a device, writing zeros to the media. The device
can be
a whole-disk or a partition. In either case, in order
to be
useful again, zeroed whole-disks will need to be
(re)parti-
tioned, or zeroed partitions will need to be
(re)formatted
with a file system, e.g. by using the partitionDisk,
eraseDisk, or eraseVolume verbs.
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;
how-
ever, 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 pre-
vent inadvertent identification by software, e.g. as
filesys-
tem data.
Ownership of the affected disk is required.
randomDisk [times] device
Erase a whole disk, writing random data to the media.
Times
is the optional (defaults to 1) number of times to
write ran-
dom information. The device can be a whole-disk or a
parti-
tion. In either case, in order to be useful again,
randomized
whole-disks will need to be (re)partitioned, or
randomized
partitions will need to be (re)formatted with a file
system,
e.g. by using the partitionDisk, eraseDisk, or
eraseVolume
verbs. 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. Ownership of the affected disk
is
required.
secureErase [freespace] level device
Erase, using a "secure" (but see the NOTE below)
method,
either a whole-disk (including all of its partitions if
parti-
tioned), or, only the free space (not in use for files)
on a
currently-mounted volume. Secure erasing makes it
harder to
recover data using "file recovery" software.
Erasing a whole-disk will leave it useless until it is
parti-
tioned 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:
· 0 - Single-pass zero fill erase.
· 1 - Single-pass random fill erase.
· 2 - Seven-pass erase, consisting of zero
fills and
all-ones fills plus a final random fill.
· 3 - Gutmann algorithm 35-pass erase.
· 4 - Three-pass erase, consisting of two
random fills
plus a final zero fill.
NOTE: This kind of secure erase is no longer considered
safe.
Modern devices have wear-leveling, block-sparing, and
possi-
bly-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
(File-
Vault).
partitionDisk device [numberOfPartitions] [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
parti-
tions 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.
The optional partitioning scheme parameter forces a
particular
partitioning scheme; if not specified, a suitable
default is
chosen. They are:
· APM[Format] specifies that an Apple Partition
Map
scheme should be used. This is the
traditional
Apple partitioning scheme used to start up a
Pow-
erPC-based Macintosh computer, to use the
disk as a
non-startup disk with any Mac, or to create a
multi-
platform compatible startup disk.
· MBR[Format] specifies that a Master Boot
Record
scheme should be used. This is the
DOS/Windows-com-
patible partitioning scheme.
· GPT[Format] specifies that a GUID
Partitioning Table
scheme should be used. This is the
partitioning
scheme used to start up an Intel-based
Macintosh
computer.
For each partition, a triplet of the desired file
system for-
mat, 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 names are of the form jhfs+, HFS+,
MS-DOS,
etc.; a list of formattable file systems
(more pre-
cisely, specific file system personalities
exported
by the installed file system bundles) and
common
aliases is available from the listFilesystems
verb.
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 for-
matter 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.
· Names are the initial volume names; they must
con-
form to file system specific restrictions.
If a name of %noformat% is specified, then
the par-
tition 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.
· Sizes are floating point numbers followed by
a let-
ter or percent sign as described in the SIZES
sec-
tion at the end of this page (e.g. 165536000,
55.3T,
678M, 75%, R).
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
penulti-
mate 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.
resizeVolume device limits | mapsize [-plist] | R | size
[numberOfPartitions] [part1Format part1Name part1Size
part2Format part2Name part2Size part3Format part3Name
part3Size ...]
Non-destructively resize a volume (partition); you may
increase or decrease its size. Alternatively, take no
action
and print information.
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 con-
ditions 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
parti-
tions 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
capi-
tal 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.
splitPartition device [numberOfPartitions] [part1Format part1Name
part1Size part2Format part2Name part2Size part3Format
part3Name part3Size ...]
Destructively split a volume into multiple partitions.
You
must supply a list of new partitions to create in the
space of
the old partition; specify these with the
numberOfPartitions,
format, name, and size parameters in the same manner as
the
triplet description for the partitionDisk verb.
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.
mergePartitions [force] format name fromDevice toDevice
Merge two or more partitions on a disk. All data on
merged
partitions other than the first will be lost. Data on
the
first partition will be lost as well if the force
argument is
given.
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 par-
tition; 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.
addPartition device format name size
Create a new partition following an existing partition.
The
new partition will start immediately beyond the end
(start +
size) of the existing partition.
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
descrip-
tion 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 for-
matting 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
interpreta-
tion.
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.
APFS | ap apfsVerb [...]
Apple APFS is a system of virtual volumes. APFS verbs
can be
used to create, manipulate and destroy APFS Containers
and
their APFS Volumes. Apple APFS defines these types of
objects:
· Container - An APFS Container imports one or
more
APFS Physical Store disks and exports zero or
more
APFS Volume disks. Zero or more APFS
Containers can
exist in (might be attached to) the system at
any
one time.
While attached, the "handle" by which an APFS
Con-
tainer 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
(capac-
ity) 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.
· Physical Store - An APFS Physical Store is a
disk
which is imported into (that is, which backs,
indeed
defines) an APFS Container. An APFS Container
can
import more than one Physical Store, e.g. for
Fusion-style Containers.
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.
· Volume - An APFS Volume is an [un]mountable
file
system volume which is exported from an APFS
Con-
tainer. Zero or more APFS Volumes may be
exported
out of an APFS Container.
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
Con-
tainer, 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
mini-
mum 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 run-
ning 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 sup-
ported; 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 Vol-
umes 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.
· Snapshot - An APFS Snapshot represents a
read-only
copy of its parent (or "base") APFS Volume,
frozen
at the moment of its creation. An APFS
Volume can
have zero or more associated APFS Snapshots.
APFS Snapshots are normally not discoverable
unless
the "base" or one of the snapshots is
mounted. APFS
Snapshots are uniquely identified with a UUID
(pre-
ferred) 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
duplica-
tion 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
possi-
bility of ever reverting to that Snapshot's
state,
but does not affect the Volume's present-time
con-
tent.
An APFS Snapshot mount point's "source
device" (its
statfs(2) f_mntfromname shown by the mount(8)
com-
mand) 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" Vol-
ume'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.
· Volume Group - Collections of APFS Volumes
can be
associated with each other via an APFS Volume
Group.
Zero or more APFS Volume Groups may exist on
any
given APFS Container. The "members" (APFS
Volumes)
of any particular APFS Volume Group must all
be on
the same APFS Container. There is no such
thing as
an "empty" (zero-member) APFS Volume Group.
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 rea-
sons 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.
Back-
ups 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
descrip-
tions and individual arguments.
list [-plist] [containerReferenceDevice]
Display APFS objects as a tree. APFS
Container(s)
are shown with their imported Physical
Store(s) and
exported Volume(s).
All currently-attached APFS Containers in
the sys-
tem 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 out-
put.
convert device [-dryrun] [-prebootSource
yourStagingDirectory]
[-noPrebootAdditions]
Non-destructively convert an HFS volume to
an APFS
Container with a single (but see below) APFS
Vol-
ume. The APFS Container can later be
manipulated
(e.g. adding and deleting APFS Volumes) as
usual.
This verb can be used to convert nonbootable
"data"-only volumes as well as "macOS"
volumes (see
below).
The source HFS volume can be located on a
GPT par-
tition 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
parti-
tion(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-bear-
ing (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
render-
ing) items are automatically added to your
direc-
tory prior to conversion and are not removed
after-
wards. You can opt-out of automatic item
addition
with the -noPrebootAdditions option.
Ownership of the affected disks is required.
create device [device] name
Convenience verb which creates an empty APFS
Con-
tainer and then adds one APFS Volume with
the given
name. The APFS Volume will have default
attributes
such as no encryption, no capacity reserve
nor
quota, etc. If you specify more than one
device, a
Fusion Container is created, with the
performance
parts assigned automatically. This is a
combina-
tion of the diskutil apfs createContainer
and
diskutil apfs addVolume verbs.
Ownership of the affected disks is required.
createContainer [-main] device [-secondary] [device]
Create an empty APFS Container. The
device(s)
specified become APFS Physical Stores. If
you
specify more than one device, a Fusion
Container is
created.
For Fusion cases, if you do not explicitly
use the
-main and -secondary options, the
performance
duties are assigned automatically; this is
pre-
ferred. 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 par-
tition.
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
Vol-
umes 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.
deleteContainer [-force] containerReferenceDevice |
physicalStoreDevice [newName] [newFormat
newName
newSize]
Destroy an existing APFS Container,
including all
of its APFS Volumes. Data on all of those
volumes
will be lost.
You can identify the APFS Container by its
Con-
tainer 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 cur-
rently supported.
If your APFS Container is damaged, a
Container Ref-
erence for it might not exist or it might
not be
functional. In this case, you can reclaim
your for-
mer 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 Con-
tainer 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.
resizeContainer containerReferenceDevice |
physicalStoreDevice
limits [-plist] | size [part1Format
part1Name
part1Size part2Format part2Name part2Size
part3Format part3Name part3Size ...]
Resize an existing APFS Container by
specifying
either an APFS Container Reference
(preferred) or
an APFS Physical Store partition, plus a
proposed
new size. Alternatively, take no action and
print
constraint information. The operation is
live,
non-destructive, and does not mount or
unmount any
APFS Volumes.
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
con-
straints; the -plist option will print this
infor-
mation 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 tar-
geted 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.
addVolume containerReferenceDevice filesystem name
[-passprompt] | [-passphrase passphrase] |
[-stdinpassphrase] [-passphraseHint
passphraseHint]
[-reserve reserve] [-quota quota] [-role
roles]
[-group[With] | -sibling groupDevice]
[-nomount]
[-mountpoint mountpoint]
Add a new APFS Volume to an existing APFS
Con-
tainer. Files can then be stored on this
newly-cre-
ated APFS Volume.
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
begin-
ning of its existence (as opposed to having
encryp-
tion 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 spec-
ify 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 vol-
ume'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 par-
ent 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 the
characters
BRVITSDUNEXHLCYG, or 0 as a no-op for
scripting
convenience; the meaning of these characters
is,
respectively: B=Preboot (boot loader),
R=Recovery,
V=VM (swap space), I=Installer (temporary
usage),
T=Backup (Time Machine), S=System, D=Data,
U=User,
N=Baseband, E=Update, X=XART (hardware
security),
H=Hardware, L=Internal, C=Sidecar (Time
Machine),
Y=Enterprise (data), and G=iDiagnostics
(EFI).
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
direc-
tory yourself when you unmount.
Ownership of the affected disks is required.
deleteVolume volumeDevice
Remove the given APFS Volume from its APFS
Con-
tainer. All of the Volume's data will be
lost.
Additionally, a best-effort (error ignored)
attempt
is made to remove any corresponding XART,
Preboot,
and Recovery entries.
Ownership of the affected disks is required.
deleteVolumeGroup volumeGroupUUID
Remove all APFS Volumes belonging to the
given APFS
Volume Group from its APFS Container. All
of the
Volumes' data will be lost. Additionally, a
best-
effort (error ignored) attempt is made to
remove
any corresponding XART, Preboot, and
Recovery
entries for each Volume. It is then
positively
verified that the Volume Group no longer
exists.
Removal will not start unless all Volumes in
the
Group can first be successfully unmounted.
Ownership of the parent APFS Container is
required.
eraseVolume volumeDevice -name newName [-passprompt] |
[-passphrase passphrase] |
[-stdinpassphrase]
[-passphraseHint passphraseHint] [-role
roles]
[-group[With] | -sibling groupDevice]
Erase the contents of an existing APFS
Volume; all
of its data will be lost. Unlike diskutil
apfs
deleteVolume, the APFS Volume is not removed
from
its APFS Container.
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.
changeVolumeRole | chrole volumeDevice roles
Change the role metadata flags of an
existing APFS
Volume.
The roles should be any combination of one
or more
of the characters
brvitsdunexhlcygBRVITSDUNEXHLCYG
in much the same manner as diskutil apfs
addVolume
above, in which unspecified flags are left
alone,
use of lower-case causes flags to be
cleared, and
use of upper-case causes flags to be set.
Alterna-
tively, 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.
unlockVolume | unlock volumeDevice [-user disk | -user
cryptoUserUUID | -recoverykeychain file]
[-passphrase passphrase] |
[-stdinpassphrase]
[-nomount | -mountpoint mountpoint]
[-systemreadwrite] [-verify] [-plist]
Unlock and mount an encrypted and locked
APFS Vol-
ume or verify a passphrase.
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 pre-
viously 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
"Sys-
tem"/"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
mount-
point 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 out-
put; 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.
lockVolume | lock volumeDevice
Unmount and lock an encrypted unlocked APFS
Volume.
This is mostly a synonym for diskutil
unmount.
Ownership of the affected disks is required.
listCryptoUsers | listUsers | listCryptoKeys | listKeys
[-plist] volumeDevice
Show all cryptographic users and
special-purpose
(e.g. recovery) "users" (keys) that are
currently
associated with the given APFS Volume, each
by
their Cryptographic User UUID and usage
"type".
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
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
associ-
ated with corresponding "Recovery Users" and
have
fixed-constant UUID values; and "Open
Directory"
users, whose UUID values match corresponding
local
macOS Open Directory account user GUIDs.
If -plist is specified, then a property list
will
be emitted instead of the normal
user-readable out-
put.
changePassphrase | changeCryptoUserPassphrase | passwd
volumeDevice -user disk | cryptoUserUUID
[-oldPassphrase oldPassphrase |
-oldStdinpassphrase] [-newPassphrase
newPassphrase
| -newStdinpassphrase]
Change the passphrase of the given
cryptographic
user associated with the given APFS Volume.
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.
setPassphraseHint | setCryptoUserPassphraseHint | hint
volumeDevice -user disk | cryptoUserUUID
-hint
hintMessage | -clear
Set an arbitrary hint string to aid recall
of a
passphrase for the given cryptographic user
associ-
ated with the given APFS Volume. Specifying
-clear
will clear any existing hint (no hint is the
default).
Ownership of the affected disks is required.
encryptVolume | encrypt | enableFileVault volumeDevice
-user
disk | existingCryptoUserUUID [-passphrase
existingOrNewPassphrase | -stdinpassphrase]
Start encryption of a currently-unencrypted
APFS
Volume ("Enable FileVault"). Depending on
hard-
ware, the operation may be accomplished
immedi-
ately, or it may proceed "in the
background".
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/Vol-
ume 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.
decryptVolume | decrypt | disableFileVault volumeDevice
[-user
disk | existingCryptoUserUUID |
-recoverykeychain
file] [-passphrase existingPassphrase |
-stdinpassphrase]
Start decryption of a currently-encrypted
APFS Vol-
ume ("Disable FileVault"). Depending on
hardware,
the operation may be accomplished
immediately, or
it may proceed "in the background".
The APFS Volume must be in an unlocked state
before
invoking this operation. Additionally, this
opera-
tion 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.
listSnapshots | listVolumeSnapshots [-plist]
volumeDevice |
volumeSnapshotDevice
Show all APFS Snapshots currently associated
with
the given APFS Volume, each with information
such
as its Snapshot UUID, Snapshot Name, numeric
XID
identifier, and possibly other fields. If
applica-
ble, the unique APFS Snapshot which might be
limit-
ing APFS Container resizing is identified.
If you are rooted (booted) from an APFS
Snapshot,
you can specify the appropriate 3-part BSD
identi-
fier (e.g. "disk1s2s1").
If -plist is specified, then a property list
will
be emitted instead of the normal
user-readable out-
put.
deleteSnapshot volumeDevice -uuid snapshotUUID | -xid
xid |
-name snapshotName
Remove the given APFS Snapshot from its APFS
Vol-
ume. The ability to restore the state of
the APFS
Volume back to that point in its evolution
will be
lost.
Ownership of the affected disks is required.
list[Volume]Groups [-plist] [containerReferenceDevice]
Display the relationships among APFS Volumes
which
are defined by APFS Volume Groups. For each
cur-
rently-attached APFS Container in the
system, the
Container's APFS Volume Groups are shown;
for each
APFS Volume Group, the Group's membership
list of
APFS Volumes is shown.
If -plist is specified, then a property list
will
be emitted instead of the normal
user-readable out-
put.
defragment containerDevice | volumeDevice status |
enable |
disable
Manage automatic background defragmentation
of user
file data at the APFS Container or Volume
level.
Enablement of defragmentation at the APFS
Container
level means that any future Volumes which
are cre-
ated out of that Container will have
defragmenta-
tion enabled by default.
Ownership of the affected disks is required.
updatePreboot volumeDevice [-od openDirectoryPath]
Examine the given APFS Volume's
cryptographic user
(unlock) records, correlating against
matching
macOS user metadata (e.g. avatar pictures,
password
hints, etc) and use this information to
update the
target volume's associated Preboot Volume.
The Pre-
boot Volume is used at EFI firmware time to
present
a login user interface and to load and boot
macOS.
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/dslo-
cal/nodes/Default", or with / to use the
currently-
running macOS (even if volumeDevice is not).
Redi-
recting 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.
syncPatchUsers volumeDevice
Perform a specific, rarely-needed repair of
APFS
cryptographic user lock records. If the
target
volume is part of an APFS Volume Group, all
APFS
cryptographic user record lock data is
copied from
the System-role volume, if any, to the
Data-role
volume, if any.
You must never use this command unless you
know
precisely why you are doing so.
Ownership of the affected disks is required.
appleRAID | ar raidVerb [...]
AppleRAID verbs can be used to create, manipulate and
destroy
AppleRAID volumes (Software RAID). AppleRAID supports
three
basic types of RAID sets:
· "stripe" - Striped Volume (RAID 0)
· "mirror" - Mirrored Volume (RAID 1)
· "concat" - Concatenated Volume (Spanning)
Of these three basic types, only the "mirror" type
increases
fault-tolerance. Mirrors may have more than two disks
to fur-
ther increase their fault-tolerance. Striped and
concaten-
tated 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:
· RAID 50 - A striped RAID set of hardware RAID
5
disks.
· RAID 10 - A striped RAID set of mirrored RAID
sets.
· RAID 0+1 - A mirrored RAID set of striped
RAID sets.
· Concatenated Mirror - A concatenation of
mirrored
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 spec-
ifying 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.
list [-plist | UUID]
Display AppleRAID volumes with current
status and
associated member disks. If UUID is
specified,
only list the RAID set with that AppleRAID
Set
UUID. If -plist is specified, then a
property list
will be emitted instead of user-formatted
output.
The -plist and UUID arguments may not both
be spec-
ified. diskutil listRAID and diskutil
checkRAID
are deprecated synonyms for diskutil
appleRAID
list.
create mirror | stripe | concat setName format devices
...
Create a new RAID set consisting of multiple
disks
and/or RAID sets. setName is used for both
the
name of the created RAID volume and the RAID
set
itself (as displayed in list). e.g.
'diskutil cre-
ateRAID stripe MyArray JHFS+ disk1 disk2
disk3
disk4'. Ownership of the affected disks is
required. diskutil createRAID is a
deprecated syn-
onym for diskutil appleRAID create.
delete raidVolume
Destroy an existing RAID set. If the RAID
set is a
mirror with a resizable file system, delete
will
attempt to convert each of the member
partitions
back into a non-RAID volume while retaining
the
contained file system. For concatenated
RAID sets
with a resizable file system, delete will
attempt
to shrink the file system to fit on the
first mem-
ber partition and convert that to a non-RAID
vol-
ume. Ownership of the affected disks is
required.
diskutil destroyRAID is a deprecated synonym
for
diskutil appleRAID delete.
repairMirror raidVolume newDevice
Repair a degraded mirror by adding a "new"
disk
given as newDevice to the RAID mirror set
whose
exported disk device or set UUID is given as
raidVolume. The new disk must be the same
size or
larger than the existing disks in the RAID
set.
After running this command, you should
manually
remove the old (orphaned, failed) member(s)
with
diskutil appleRAID remove. Ownership of the
affected disk is required. diskutil
repairMirror
is a deprecated synonym for diskutil
appleRAID
repairMirror.
add type newDevice raidVolume
Add a new member or hot spare to an existing
RAID
set. Type can be either member or spare.
New
disks are added live, the RAID volume does
not need
to be unmounted. Mirrored volumes support
adding
both members and hot spares, concatenated
volumes
only support adding members. When adding to
a mir-
rored RAID set, the new disk must be the
same size
or larger than the existing disks in the
RAID set.
Adding a hot spare to a mirror will enable
autore-
building for that mirror. Adding a new
member to a
concatenated RAID set appends the member and
expands the RAID volume. Ownership of the
affected
disk is required. diskutil addToRAID is a
depre-
cated synonym for diskutil appleRAID add.
remove oldDevice raidVolume
Remove a member or spare from an existing
RAID set.
Old disks are removed live; the RAID volume
does
not need to be unmounted. For missing
devices,
oldDevice must be the device's UUID. Online
mirror
members with a resizable file system will be
con-
verted to non-RAID volumes, spare and
offline mem-
bers will be marked free. For concatenated
RAID
sets, only the last member can be removed.
For
resizable file systems remove will first
attempt to
shrink the concatenated RAID set so that the
file
system fits on the remaining disks.
Ownership of
the affected disk is required. diskutil
removeFromRAID is a deprecated synonym for
diskutil
appleRAID remove.
enable mirror | concat device
Convert a non-RAID disk partition containing
a
resizable file system (such as JHFS+) into
an
unpaired mirror or single disk concatenated
RAID
set. Disks that were originally partitioned
on Mac
OS X 10.2 Jaguar or earlier or were
partitioned to
be Mac OS 9 compatible may not be resizable.
Own-
ership of the affected disk is required.
diskutil
enableRAID is a deprecated synonym for
diskutil
appleRAID enable.
update key value raidVolume
Update the key value parameters of an
existing RAID
set. Valid keys are:
· AutoRebuild - If true, the system
attempts to rebuild degraded
mirrored
volumes automatically. When
looking for
devices for rebuild, AppleRAID
first
looks for hot spares and then
degraded
members. Use a value of "1" for
true and
"0" for false.
· SetTimeout - Controls how long the
system
waits (in seconds) for a missing
device
before degrading a mirrored raid
set.
Also controls the amount of time
you have
to disconnect all devices from an
unmounted mirror without degrading
it.
Ownership of the affected disk is required.
diskutil updateRAID is a deprecated synonym
for
diskutil appleRAID update.
coreStorage | cs coreStorageVerb [...]
CoreStorage verbs can be used to gather information
about, and
to remove, CoreStorage volumes.
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
flexibil-
ity 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:
· Logical Volume Group (LVG)
· Physical Volume (PV)
· Logical Volume Family (LVF)
· Logical Volume (LV)
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
repre-
sents a device that feeds the LVG storage space; a PV
is nor-
mally 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 Vol-
umes (LVs). However, only and exactly one LV per LVF
is sup-
ported.
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.
list [-plist | UUID]
Display a tree view of the CoreStorage world
for
all current logical volume groups (LVGs)
with mem-
ber disks (PVs) and exported volumes (LVFs
and
LVs), with properties and status for each
level.
If -plist is specified then a property list
will be
emitted instead of the formatted tree
output; the
UUIDs can be used with the diskutil
coreStorage
information verb to get properties for the
object
represented by that UUID. If UUID is
specified
then an attempt is made to list only that
UUID
(whatever type of CoreStorage object it may
repre-
sent). The -plist and UUID arguments may
not both
be specified.
info | information [-plist] UUID | device
Display properties of the CoreStorage object
(LVG,
PV, LVF, or LV) associated with the given
CoreStor-
age UUID or disk.
delete | deleteLVG lvgUUID | lvgName
Delete a CoreStorage logical volume group.
All log-
ical volume families with their logical
volumes are
removed, the logical volume group is
destroyed, and
the now-orphaned physical volumes are erased
and
partition-typed as Journaled HFS+.
unlockVolume | unlockLV [-nomount] lvUUID
[-stdinpassphrase] |
[-passphrase passphrase] |
[-recoverykeychain file]
Unlock a logical volume and file system,
causing it
to be attached and mounted. Data is then
accessi-
ble in plain form to the file system and
applica-
tions, while the on-physical-disk backing
bytes
remain in encrypted form. A credential must
be
supplied; you must supply either a "Disk"
user
passphrase or a recovery keychain 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 vol-
umes (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.
DEVICES
A device parameter for any of the above commands (except
where explicitly
required otherwise) can usually be any of the following:
· The disk identifier (see below). Any entry of the form
of
disk*, e.g. disk1s9.
· The device node entry containing the disk identifier.
Any
entry of the form of /dev/[r]disk*, e.g. /dev/disk2.
· The volume mount point. Any entry of the form of
/Volumes/*,
e.g. /Volumes/Untitled. In most cases, a "custom"
mount point
e.g. /your/custom/mountpoint/here is also accepted.
· The URL form of any of the volume mount point forms
described
above. E.g. file:///Volumes/Untitled or file:///.
· A UUID. Any entry of the form of e.g.
11111111-2222-3333-4444-555555555555. The UUID can be a
"media" UUID which IOKit places in an IOMedia node as
derived
from e.g. a GPT map's partition UUID, or it can be an
AppleRAID
(or CoreStorage) set (LV) or member (PV) UUID.
· A volume name, e.g. Untitled. This match is only
attempted if
the given device is not of the form [/dev/][r]disk*, nor
[/Volumes/]*. The match attempt is against the
intrinsic vol-
ume label, not against the terminal component, if
mounted, of
its mount point.
DISK IDENTIFIER
The (BSD) disk identifier string variously identifies a
physical or logi-
cal 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:
· U is the device unit. It may refer to hardware (e.g. a
hard
drive, optical drive, or memory card) or a virtual
"drive" con-
structed by software (e.g. an AppleRAID Set, Apple Disk
Image,
CoreStorage LV, etc).
· C is an APFS Container. This is a virtual disk
constructed by
APFS to represent a collection of APFS Volumes.
Multiple APFS
Containers can be active simultaneously.
· Q is the session and is only included for optical media;
it
refers to the number of times recording has taken place
on the
currently-inserted medium (disc).
· P is a partition in some partitioning scheme. A
partitioning
scheme divides up a device unit and is also called a
"partition
map" or simply a "map". Upon a partition, the raw data
that
underlies a user-visible file system is usually present,
but it
may also contain specialized data for certain 3rd-party
data-
base programs, or data required for the system software
(e.g.
EFI partitions, booter partitions, APM partition map
data,
etc), or, notably, it might contain backing-store
physical vol-
umes for AppleRAID, CoreStorage, APFS, or other
(3rd-party)
Storage Systems. For example, a partition disk0s2 might
con-
tain APFS data and have a partition type of Apple_APFS;
this
partition would then be termed an APFS Physical Store,
out of
which an APFS Container disk1 is defined, out of which
an APFS
Volume disk1s1 is exported.
· V is an APFS Volume; it refers to a virtual logical
volume that
is shared out of an APFS Container. For example,
exported from
an APFS Container designated as disk1 there might be an
APFS
Volume disk1s1, mountable as a file system and usable
for file
storage via its mountpoint path.
· S is an APFS Snapshot; it refers to a frozen moment in
time of
the state of files on an APFS Volume. For example, if
APFS
Container disk6 has an APFS Volume disk6s3, and two APFS
Snap-
shots have been "taken" on it, these, when mounted,
might be
designated as disk6s3s1 and disk6s3s2. Zero or more
snapshots
can be persistently defined on a volume, but only
"active"
(mounted) snapshots have disk identifiers.
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.
SIZES
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-sen-
sitive. 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
"remain-
der").
Power-of-ten suffixes:
· B is bytes (not blocks) where the multiplier is 1. This
suffix
may be omitted.
· K[B] is power of ten kilobytes where the multiplier is
1000 (1
x 10^3).
· M[B] is power of ten megabytes where the multiplier is
1000000
(1 x 10^6).
· G[B] is power of ten gigabytes where the multiplier is
1000000000 (1 x 10^9).
· T[B] is power of ten terabytes where the multiplier is
1000000000000 (1 x 10^12).
· P[B] is power of ten petabytes where the multiplier is
1000000000000000 (1 x 10^15).
· E[B] is power of ten exabytes where the multiplier is
1000000000000000000 (1 x 10^18).
Power-of-two suffixes:
· Ki[B] is power of two kibibytes where the multiplier is
1024 (1
x 2^10).
· Mi[B] is power of two mebibytes where the multiplier is
1048576
(1 x 2^20).
· Gi[B] is power of two gibibytes where the multiplier is
1073741824 (1 x 2^30).
· Ti[B] is power of two tebibytes where the multiplier is
1099511627776 (1 x 2^40).
· Pi[B] is power of two pebibytes where the multiplier is
1125899906842624 (1 x 2^50).
· Ei[B] is power of two exbibytes where the multiplier is
1152921504606846976 (1 x 2^60).
The following are useful when working with devices and partition
maps:
· S | UAM ("sectors") is 512-byte units
(device-independent)
where the multiplier is always 512.
· DBS ("device block size") is the device-dependent native
block
size of the encompassing whole disk, if applicable,
where the
multiplier is often 512, but not always; indeed it might
not be
a power of two.
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:
· 0 (the number zero) is a request to allocate "all
possible".
This may mean different things in different contexts.
For par-
tition maps, this requests allocation until the start of
the
following partition or the end of the partition map's
allocat-
able space.
· % (with a preceding number) is a percentage of the
whole-disk
size, the partition map size, or other allocatable size,
as
appropriate by context. Use of % is not supported in
all situ-
ations.
· R (with no preceding number) specifies the remainder of
the
whole-disk size or other allocatable size after all
other
triplets in the group are taken into account. It need
not be
in the last triplet. It must only appear in at most one
triplet among all triplets. Use of R is not supported
in all
situations; in some such cases, a value of 0 is more
appropri-
ate.
You can provide an operating system-defined constant value as
follows:
· %recovery% (with no preceding number) is the customary
size of
pre-macOS-13.0 Recovery Partitions.
Note again that B refers to bytes and S and UAM refer to a
constant mul-
tiplier 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).
FORMAT
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
per-
sonalities (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+".
EXAMPLES
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
SEE ALSO
hdiutil(1), mount(8), umount(8), diskmanagementd(8),
diskmanagementstartup(8), diskarbitrationd(8), corestoraged(8),
fdesetup(8), ioreg(8), newfs_hfs(8), fsck_hfs(8), authopen(1),
hfs.util(8), msdos.util(8), ufs.util(8), drutil(1), vsdbutil(8),
apfs.util(8), fsck_apfs(8), mount_apfs(8), newfs_apfs(8)
ERRORS
diskutil will exit with status 0 if successful or 1 if it
cannot complete
the requested operation; this includes cases in which usage text
is
printed. Before diskutil returns with status 1, 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.
HISTORY
The eraseDisk and partitionDisk verbs had an option to add
Mac OS 9 driv-
ers (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.
macOS 24 July 2020 macOS