How to Change an Encrypted APFS Volume Passphrase in macOS Terminal Using diskutil

Regularly rotating encryption credentials is a standard security requirement for enterprise compliance, sensitive data backups, and shared external storage. In macOS, external SSDs, USB flash drives, and secondary storage containers formatted with Apple File System (APFS) encryption are protected by a passphrase that wraps the underlying Volume Encryption Key (VEK). While users can change FileVault login passwords for their personal user accounts in System Settings, modifying the encryption passphrase of an external APFS storage drive or standalone container typically requires command-line intervention.

In macOS Terminal, the native diskutil apfs subsystem includes a dedicated verb: changePassphrase. This command rotates the key-wrapping passphrase in-place without re-encrypting the underlying data or requiring a lengthy drive backup.

How Passphrase Rotation Works in APFS

Understanding how APFS manages volume keys explains why passphrase rotation is instantaneous:

• Underlying Data is NOT Re-encrypted: APFS does not decrypt and re-encrypt the gigabytes of data stored on disk. The Volume Encryption Key (VEK) that encrypts the actual physical blocks remains unchanged.
• Key Encryption Key (KEK) Update: Changing the passphrase merely unwraps the volume key using the existing password and re-wraps it with a new Key Encryption Key derived from your new password. The entire process takes less than a second.
• Container Safety: The operation modifies strictly the APFS volume metadata header, leaving all stored files, directory catalogs, and sibling volumes completely untouched.

Identifying Your Encrypted Volume Identifier

Before rotating credentials, identify the disk identifier of your encrypted APFS volume:

diskutil apfs list

Locate your target volume (e.g., /dev/disk3s1). Verify that the FileVault / Encryption property indicates Yes (Unlocked).

Changing the Passphrase Interactively (Recommended)

To avoid exposing passwords in your shell history (such as ~/.zsh_history), change the passphrase interactively:

diskutil apfs changePassphrase /dev/disk3s1

Terminal will display three consecutive prompts:

1. Old Passphrase: Enter the currently active password.
2. New Passphrase: Enter your desired replacement password.
3. Repeat New Passphrase: Confirm the replacement password.

Upon successful verification, Terminal outputs:

Passphrase changed successfully for APFS Volume disk3s1

Supplying Passphrases Directly (Scripted Automation)

For administrative scripts or fleet provisioning workflows running inside secure automation pipelines, supply passwords directly via command flags:

diskutil apfs changePassphrase /dev/disk3s1 -oldPassphrase "OldSecret123" -newPassphrase "NewSecurePass456"

Verifying the Updated Passphrase

To confirm that your updated credentials operate correctly without rebooting your Mac:

1. Lock and unmount the volume to evict cached keys from kernel memory:

   diskutil apfs lockVolume /dev/disk3s1

2. Re-authenticate using the new passphrase:

   diskutil apfs unlockVolume /dev/disk3s1

3. Enter your new password when prompted. The volume will unlock and mount cleanly to /Volumes/VolumeName.

Command Reference Matrix

The table below summarizes common diskutil apfs password and security verbs:

Command	Required Inputs	Operational Effect
diskutil apfs changePassphrase diskNsM	Interactive Prompts	Securely rotates volume encryption passphrase in-place.
diskutil apfs unlockVolume diskNsM	Passphrase	Authenticates credentials and mounts the encrypted volume.
diskutil apfs lockVolume diskNsM	None	Unmounts volume and flushes cryptographic keys from RAM.
diskutil apfs listCryptoUsers diskNsM	None	Displays cryptographic user UUIDs bound to the volume.

Frequently Asked Questions

What happens if I forget the current old passphrase?

If you lose the old passphrase, you cannot rotate credentials or access data on the volume unless an institutional recovery key or personal FileVault recovery key was configured during initial encryption. APFS uses industry-standard AES-XTS cryptography with zero backdoors.

Can I change the passphrase while the volume is actively locked?

No. The volume must be recognized and unlocked by macOS so the kernel can verify the existing Key Encryption Key before writing the updated wrapper header.