Apple File System (APFS) incorporates robust volume-level encryption natively into macOS. When you connect an encrypted external drive or access an internal FileVault volume, Finder typically prompts for an authentication password. However, when performing headless system administration over SSH, automating backup scripts, or recovering data from macOS Recovery Mode, graphical dialogues are unavailable. You must unlock and mount encrypted APFS containers directly from the command line.
The native diskutil apfs subsystem provides specialized verbs to authenticate cryptographic keys, unlock APFS volumes into memory, and mount file structures safely.
Understanding the Encrypted APFS Architecture
In APFS, encryption keys are managed at the volume level within a shared storage container:
- Container Allocation: A single physical partition (e.g.,
/dev/disk2s2) hosts an APFS Container (e.g.,disk3), which can host multiple independent volumes. - Volume Encryption State: An encrypted APFS volume remains locked as an opaque cryptographic block until valid credentials (a user passphrase, recovery key, or institutional key) derive the Volume Encryption Key (VEK).
- Unlock vs Mount: Unlocking validates credentials and loads the cryptographic keys into kernel memory. Mounting links the decrypted directory tree to a specific mount point path (such as
/Volumes/BackupDrive).
Locating the Target Encrypted Volume Identifier
Before issuing unlock commands, identify the device node assigned to the locked volume:
diskutil apfs listReview the output to find your encrypted volume. Note key properties:
- Device Identifier: e.g.,
disk3s2. - FileVault / Encryption: Indicates
Yes (Locked). - Volume UUID: A persistent alphanumeric string uniquely identifying the volume across reboots.
Unlocking the Encrypted APFS Volume
You can unlock an APFS volume using several authentication methods depending on your automation and security requirements:
1. Interactive Passphrase (Secure Prompt)
To avoid exposing passwords in plain-text shell histories, prompt interactively for credentials:
diskutil apfs unlockVolume /dev/disk3s2Terminal will display: Passphrase:. Enter the volume password and press Enter. Upon successful authentication, diskutil unlocks and automatically mounts the volume.
2. Supplying the Passphrase Directly
For automated backup scripts running within secure environments, supply the password directly via the -passphrase flag:
diskutil apfs unlockVolume /dev/disk3s2 -passphrase "YourSecretPassword"3. Unlocking Using a FileVault Recovery Key
If user passwords have been forgotten, unlock using the 24-character alphanumeric FileVault recovery key:
diskutil apfs unlockVolume /dev/disk3s2 -recoverykey "XXXX-XXXX-XXXX-XXXX-XXXX-XXXX"Command Reference Matrix
The table below summarizes common diskutil apfs volume management commands:
| Command | Required Privileges | Operational Role |
|---|---|---|
diskutil apfs unlockVolume diskNsM |
Standard / Sudo | Authenticates passphrase and mounts the decrypted volume. |
diskutil apfs unlockVolume diskNsM -nomount |
Standard / Sudo | Unlocks cryptographic keys into memory without mounting to the filesystem. |
diskutil apfs lockVolume diskNsM |
Standard / Sudo | Unmounts the volume and evicts cryptographic keys from memory. |
diskutil apfs listCryptoUsers diskNsM |
Standard | Lists all authorized cryptographic user UUIDs and recovery key status. |
Locking and Dismounting Encrypted Volumes
When maintenance or backup tasks are complete, you must lock the volume to ensure cached encryption keys are purged from kernel RAM:
diskutil apfs lockVolume /dev/disk3s2The terminal will confirm: Volume disk3s2 on APFS Container disk3 locked and unmounted.
Frequently Asked Questions
What is the difference between diskutil unmount and diskutil apfs lockVolume?
Running diskutil unmount merely detaches the volume from the filesystem hierarchy while leaving encryption keys in RAM, allowing immediate re-mounting without re-entering passwords. Running lockVolume completely purges the cryptographic keys from kernel memory.
Why does unlockVolume return “Error: -69584: A required key was not found”?
This error indicates that the provided passphrase or recovery key is incorrect, or that the cryptographic metadata on the APFS container is corrupted. Verify credentials or run diskutil apfs updatePreboot if troubleshooting internal startup disks.