vielleicht mit DiskUtil?
DISKUTIL(8) System Manager's Manual DISKUTIL(8)
NAME
diskutil – modify, verify and repair local disks
SYNOPSIS
diskutil [quiet] verb [subVerb] [options]
DESCRIPTION
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.
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
arguments.
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
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.
info | information [-plist] device | -all
Get detailed information about a specific whole disk or
partition. 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
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.
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
personalities. 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)).
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.
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
partitions 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
partition.
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
constructs such as software RAID or direct data.
Additionally, removable media will become eligible for safe
manual removal; automatically-removable media will begin its
physical (motorized) 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
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.
mountDisk device
Mount all mountable and UI-browsable volumes on the given
partition map; that is, a mount is attempted on the directly-
mountable volume, if any, on each of the whole disk's
partitions. 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-
specific 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
different 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
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.
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
Database 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),
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.
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
supported. 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
System Partition, the integrity of any Core Storage Physical
Volume 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
Physical 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"
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.
eraseDisk [-noEFI] 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.
If -noEFI is specified, do not create EFI partition on the
target disk.
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
system 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)partitioned, 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;
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.
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
random information. The device can be a whole-disk or a
partition. 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
partitioned), 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
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:
• 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
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).
partitionDisk device [-noEFI] [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
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:
• APM[Format] specifies that an Apple Partition Map
scheme should be used. This is the traditional
Apple partitioning scheme used to start up a
PowerPC-based Macintosh computer, to use the disk as
a non-startup disk with any Mac, or to create a
multiplatform compatible startup disk.
• MBR[Format] specifies that a Master Boot Record
scheme should be used. This is the DOS/Windows-
compatible 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
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 names are of the form jhfs+, HFS+, MS-DOS,
etc.; a list of formattable file systems (more
precisely, 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
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.
• Names are the initial volume names; they must
conform to file system specific restrictions.
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.
• Sizes are floating point numbers followed by a
letter or percent sign as described in the SIZES
section 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
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.
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
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.
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
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.
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
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.
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
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.
• 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
Container. 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
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.
• 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
(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.
• 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
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.
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
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.
convert device [-dryrun] [-prebootSource yourStagingDirectory]
[-noPrebootAdditions]
Non-destructively convert an HFS volume to an APFS
Container with a single (but see below) APFS
Volume. 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
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.
create device [device] name
Convenience verb which creates an empty APFS
Container 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 combination 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
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.
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
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.
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
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.
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
Container. Files can then be stored on this newly-
created 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
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
no
NAME
diskutil – modify, verify and repair local disks
SYNOPSIS
diskutil [quiet] verb [subVerb] [options]
DESCRIPTION
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.
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
arguments.
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
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.
info | information [-plist] device | -all
Get detailed information about a specific whole disk or
partition. 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
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.
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
personalities. 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)).
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.
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
partitions 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
partition.
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
constructs such as software RAID or direct data.
Additionally, removable media will become eligible for safe
manual removal; automatically-removable media will begin its
physical (motorized) 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
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.
mountDisk device
Mount all mountable and UI-browsable volumes on the given
partition map; that is, a mount is attempted on the directly-
mountable volume, if any, on each of the whole disk's
partitions. 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-
specific 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
different 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
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.
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
Database 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),
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.
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
supported. 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
System Partition, the integrity of any Core Storage Physical
Volume 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
Physical 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"
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.
eraseDisk [-noEFI] 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.
If -noEFI is specified, do not create EFI partition on the
target disk.
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
system 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)partitioned, 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;
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.
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
random information. The device can be a whole-disk or a
partition. 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
partitioned), 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
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:
• 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
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).
partitionDisk device [-noEFI] [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
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:
• APM[Format] specifies that an Apple Partition Map
scheme should be used. This is the traditional
Apple partitioning scheme used to start up a
PowerPC-based Macintosh computer, to use the disk as
a non-startup disk with any Mac, or to create a
multiplatform compatible startup disk.
• MBR[Format] specifies that a Master Boot Record
scheme should be used. This is the DOS/Windows-
compatible 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
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 names are of the form jhfs+, HFS+, MS-DOS,
etc.; a list of formattable file systems (more
precisely, 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
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.
• Names are the initial volume names; they must
conform to file system specific restrictions.
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.
• Sizes are floating point numbers followed by a
letter or percent sign as described in the SIZES
section 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
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.
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
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.
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
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.
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
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.
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
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.
• 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
Container. 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
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.
• 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
(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.
• 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
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.
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
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.
convert device [-dryrun] [-prebootSource yourStagingDirectory]
[-noPrebootAdditions]
Non-destructively convert an HFS volume to an APFS
Container with a single (but see below) APFS
Volume. 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
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.
create device [device] name
Convenience verb which creates an empty APFS
Container 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 combination 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
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.
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
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.
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
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.
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
Container. Files can then be stored on this newly-
created 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
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
no