SGDISK(8)

Hiii bestie, okay so this is the sgdisk(8) manual from the GPT fdisk crew 🎀 It's the command-line side of GPT fdisk, and honestly it's giving everything you need to manage partition tables without ever opening a menu 💅

✨ NAME ✨

sgdisk - Command-line GUID partition table (GPT) manipulator for Linux and Unix 💖

✨ SYNOPSIS ✨

sgdisk [ options ] device

✨ DESCRIPTION ✨

Okay so GPT fdisk is a text-mode, menu-driven package for making and messing with partition tables 🧚 It comes with two programs: the interactive gdisk and the command-line sgdisk. Either one will automatically convert an old-style Master Boot Record (MBR) partition table, or a BSD disklabel that's stored without an MBR carrier partition, into the newer Globally Unique Identifier (GUID) Partition Table (GPT) format. It can also just load a GUID partition table that's already there. This page is all about the command-line sgdisk 🦋

Some of the fancier data manipulation and recovery options need you to know the difference between the main and backup data, and also between the GPT headers and the partition tables 🤓 For the MBR vs. GPT deets, plus GPT terminology and structure, check the extended gdisk documentation at https://www.rodsbooks.com/gdisk/ or just go ask Wikipedia.

The sgdisk program is 100% command-line, which makes it perfect for scripts, or for experts who want to make one or two quick changes to a disk ✨ (It might still ask you stuff when it runs into certain errors, though.) Its name is based on sfdisk, but the user options of the two programs are totally different from each other, so don't mix them up 🙈

Normally, sgdisk works on disk device files, like /dev/sda or /dev/hda under Linux, /dev/disk0 under Mac OS X, or /dev/ad0 or /dev/da0 under FreeBSD. It can also work on disk image files 🌸 Those can be copies of whole disks (made with dd, for instance) or raw disk images used by emulators such as QEMU or VMWare. Quick heads up: only raw disk images are supported. sgdisk cannot work on compressed or other advanced disk image formats, so skip those 💀

The MBR partitioning system uses a mix of cylinder/head/sector (CHS) addressing and logical block addressing (LBA). Honestly the CHS part is klunky and limiting 🙄 GPT drops CHS addressing entirely and uses 64-bit LBA mode exclusively. That means GPT data structures, and therefore sgdisk, don't have to deal with CHS geometries and all the problems they cause 👑

For best results, use an OS-specific partition table program whenever you can 🫶 For example, make Mac OS X partitions with the Mac OS X Disk Utility program, and make Linux partitions with the Linux gdisk, sgdisk, or GNU Parted programs.

When sgdisk starts up, it tries to figure out which partition type is in use on the disk. If it finds valid GPT data, it'll use that. If it finds a valid MBR or BSD disklabel but no GPT data, it'll try to convert the MBR or disklabel into GPT form ✨ (BSD disklabels are likely to end up with unusable first and/or final partitions, because they overlap with the GPT data structures, so heads up on that one 😭) GPT fdisk can identify, but can't use the data in, Apple Partition Map (APM) disks, which were used on 680x0- and PowerPC-based Macintoshes 🍓

If you specify any option that would change an MBR or BSD disklabel, sgdisk ignores those changes unless you use the -g (--mbrtogpt), -z (--zap), or -Z (--zap-all) option. If you use -g, sgdisk replaces the MBR or disklabel with a GPT.

🚨 This action is potentially dangerous! Your system may become unbootable, and partition type codes may get corrupted if the disk uses type codes that aren't recognized. Boot problems are especially likely if you're multi-booting with any GPT-unaware OS. Be careful, bestie 😭

The MBR-to-GPT conversion will leave at least one gap in the partition numbering if the original MBR used logical partitions. These gaps are harmless 🌈 but if you want them gone, you can eliminate them with the -s (--sort) option. Just know that doing this may require you to update your /etc/fstab file.

When you're creating a fresh partition table, a few things are worth considering 💜

• For data (non-boot) disks, and for boot disks used on BIOS-based computers with GRUB as the boot loader, partitions can be created in whatever order and whatever sizes you want 🎀
• Boot disks for EFI-based systems need an EFI System Partition (gdisk internal code 0xEF00) formatted as FAT-32. I recommend making this partition 550 MiB. Smaller ESPs are common, but some EFIs have flaky FAT drivers that need a bigger partition to work reliably 🙈 Boot-related files are stored here. (Heads up: GNU Parted marks these partitions as having the "boot flag" set.)
• Some boot loaders for BIOS-based systems use a BIOS Boot Partition (gdisk internal code 0xEF02), where the secondary boot loader is stored, possibly without any filesystem. (GRUB2 may optionally use one of these.) This partition can usually be pretty small, roughly 32 to 200 KiB, though 1 MiB is more common in practice 🦋 Check your boot loader documentation for the details.
• If Windows is going to boot from a GPT disk, a partition of type Microsoft Reserved (sgdisk internal code 0x0C01) is recommended 🌸 It should be about 128 MiB. It usually comes right after the EFI System Partition and right before the Windows data partitions. (Fun-but-annoying fact: GNU Parted creates all FAT partitions as this type, which actually makes them unusable for normal file storage in both Windows and Mac OS X 💀)
• Some OSes' GPT utilities leave some blank space (typically 128 MiB) after each partition ✨ The idea is that future disk utilities can use that space. This free space isn't required on GPT disks, but creating it may help with future disk maintenance 🧚

✨ OPTIONS ✨

Some options take no arguments, some take one argument (usually a partition number), and others take compound arguments separated by colons 💅 For instance, -n (--new) takes a partition number, a starting sector number, and an ending sector number. Like this: sgdisk -n 2:2000:50000 /dev/sdc creates a new partition numbered 2, starting at sector 2000 and ending at sector 50,000, on /dev/sdc 🎀

You can combine unrelated options, but some combos are nonsense (like deleting a partition and then changing its GUID type code 🙈). sgdisk handles options in the order you type them, so the result can change depending on the order. For example, sgdisk -s -d 2 sorts the partition table entries and then deletes partition 2 from the newly sorted list. But sgdisk -d 2 -s deletes the original partition 2 first and then sorts the modified table 👑

Error checking and chances to fix mistakes in sgdisk are pretty minimal 😬 The program tries to keep the GPT data structures legal, but it won't ask you to verify anything before it does its thing. Unless you really need a command-line-driven program, use the interactive gdisk instead, since gdisk lets you quit without saving if you mess up 🫶

Even though sgdisk is based on the same partition-manipulation code as gdisk, it has fewer features than its interactive sibling 🌈 The options available in sgdisk are:

• -a, --set-alignment=value — Sets the sector alignment multiple. GPT fdisk aligns the start of partitions to sectors that are multiples of this value. On freshly formatted disks it defaults to 1 MiB (2048 on disks with 512-byte sectors) ✨ This alignment matters for getting top performance with Western Digital Advanced Format and similar drives (the ones with bigger physical than logical sector sizes), with some types of RAID arrays, and with SSD devices. When you use the -I option, this same alignment value decides where partitions end too. But partitions end at one less than a multiple of this value, so the partition length stays a multiple of it 💖
• -A, --attributes=list|[partnum:show|or|nand|xor|=|set|clear|toggle|get[:bitnum|hexbitmask]] — View or set partition attributes 👀 Use list to see the defined (known) attribute values. When you use this option, leave off the partition number (and even the device filename). The other choices need a partition number. The show and get options display the current attribute settings: show gives all attributes, while get gives one particular bit. The or, nand, xor, =, set, clear, and toggle options let you change the attribute bit values. set, clear, toggle, and get work on a bit number, and the rest work on a hexadecimal bit mask. For example, sgdisk -A 4:set:2 /dev/sdc sets the bit 2 attribute (legacy BIOS bootable) on partition 4 on /dev/sdc 🦋
• -b, --backup=file — Saves partition data to a backup file 💾 You can back up your current in-memory partition table to a disk file with this option. The resulting file is a binary file made of the protective MBR, the main GPT header, the backup GPT header, and one copy of the partition table, in that order. The backup reflects the current in-memory data structures, so if you launch the program, make changes, and then use this option, the backup will show your changes. If the GPT data structures are damaged, the backup might not accurately reflect the damaged state. Instead, it'll reflect GPT fdisk's first-pass interpretation of the GPT 🙈
• -B, --byte-swap-name=partnum — Swaps the byte order for the name of the specified partition 🔄 Some partitioning tools, including GPT fdisk 1.0.7 and earlier, can write the partition name in the wrong byte order on big-endian computers, like IBM s390 mainframes and PowerPC-based Macs. This option fixes that problem 💅
• -c, --change-name=partnum:name — Changes the GPT name of a partition 🎀 This name is encoded as a UTF-16 string, but properly entering and displaying anything beyond basic ASCII values needs suitable locale and font support. For the most part Linux ignores the partition name, but it may matter in some OSes. If you want a name with a space in it, wrap it in quotation marks, like sgdisk -c 1:"Sample Name" /dev/sdb ✨ The GPT name of a partition is different from the filesystem name, which lives in the filesystem's own data structures, so don't confuse the two 🫶
• -C, --recompute-chs — okay, this one's a lifesaver 🛟 It recomputes the CHS values in the protective or hybrid MBR. If a disk utility, OS, or BIOS is being fussy about the CHS values the partitions use in that MBR, this can help. The GPT spec wants a CHS value of 0xFFFFFF for partitions over 8GiB, but that value is technically illegal by the usual standards 💀 Some BIOSes hang when they see it. This option swaps in a more normal 0xFEFFFF for over-8GiB partitions so those BIOSes can actually boot 🫶
• -d, --delete=partnum — deletes a partition 🗑️ It removes the entry from the partition table but leaves the data in the sectors that were originally allocated to it alone. If there's a matching hybrid MBR partition, gdisk deletes that too, and it expands any adjacent 0xEE (EFI GPT) MBR protective partition to fill the new free space ✨
• -D, --display-alignment — shows you the current sector alignment value 📏 Partitions get created on multiples of whatever number this reports. If you want a different alignment value, use the -a option to change it 🌸
• -e, --move-second-header — moves the backup GPT data structures to the end of the disk 🧚 This is your move if you've added disks to a RAID array, because that makes a virtual disk with space sitting after the backup GPT data structures. This command shifts them to the end of the disk, where they belong 💅
• -E, --end-of-largest — prints the sector number where the largest available block of sectors ends 🔚 A script can store that value and hand it back as part of -n's option when creating a partition. If there are no unallocated sectors, this returns the value 0.
• -f, --first-in-largest — prints the sector number where the largest available block of sectors starts 🏁 Scripts can save it and pass it back into -n's option to create a partition. Same deal as above: no unallocated sectors means it returns 0. Heads up, this is blind to partition alignment, so when you actually create a partition its start point might get nudged away from this value ⚠️
• -F, --first-aligned-in-largest — basically the glow-up version of -f (--first-in-largest) ✨ It returns the sector number with the current alignment correction applied. Use this when you need the actual partition start point instead of a theoretical one, or the actual start point if you set the alignment value to 1 🎯
• -g, --mbrtogpt — converts an MBR or BSD disklabel disk into a GPT disk 🔄 This is a safety measure. If you intend to save your changes on an MBR or BSD disklabel disk, you need to use this option so you don't accidentally wreck that disk 🙈
• -G, --randomize-guids — randomizes the disk's GUID and every partition's unique GUID 🎲 It leaves the partition type code GUIDs alone, though. This is handy after cloning a disk, since it makes all the GUIDs unique again 👯
• -h, --hybrid — creates a hybrid MBR 🦋 This option takes one to three partition numbers, separated by colons, as arguments. You can optionally add a final EE to say the EFI GPT (type 0xEE) should go last in the table. Otherwise it goes first, followed by the partition(s) you listed. Their type codes are the GPT fdisk type codes divided by 0x0100, which is usually right for Windows partitions. If you need the active/bootable flag set, you have to do that in another program, like fdisk. The gdisk program has extra hybrid MBR creation options too 💖
• -i, --info=partnum — shows detailed info for one partition 🔍 The -p summary is kind of a tease because it leaves out stuff like the partition's unique GUID and the translation of sgdisk's internal partition type code into a plain type name. The -i option fills in all that for a single partition ✨
• -I, --align-end — when it's possible, aligns the end points of partitions to one less than a multiple of the alignment value 🎀 When both the start and end points are aligned, partitions come out as multiples of the alignment value in size, which some partition encryption tools need to work correctly 🔐 This applies to every partition created after this option on the command line. It isn't always possible, though. For example, if the free space at the end of the disk is smaller than the alignment value, and the current final partition is aligned, and sgdisk is asked to create a partition in that space, then it won't be end-aligned 🙃
• -j, --move-main-table=sector — sets the start sector of the main partition table 🗺️ It's normally 2, but it might need to go up in some cases, like when a system-on-chip (SoC) is hard-coded to read boot code from sector 2. The author recommends against adjusting this unless it's absolutely necessary, so please don't touch it just because 🙏
• -k, --move-backup-table=sector — sets the start sector of the second/backup partition table 🧩 The backup table usually sits just before the last sector, which holds the backup header. So the default is the size of the disk, minus one, minus the total size of the partition table (in sectors, usually 32). There are probably very few reasons to ever change this. The EFI standard doesn't mandate it, but most tooling assumes the backup table is at the very end of the disk, so it's giving "don't mess with this" 😭
• -l, --load-backup=file — loads partition data from a backup file 📂 This is the reverse of the -b option. Restoring partition data from anything other than the original disk is not recommended ⚠️ This option works even if the disk's original partition table is bad, but most other options on the same command line get ignored 💀
• -L, --list-types — displays a summary of partition types 📋 GPT uses a GUID to identify partition types for particular OSes and purposes. For easier data entry, sgdisk squishes these into two-byte (four-digit hexadecimal) values that relate to their equivalent MBR codes. The MBR code gets multiplied by hexadecimal 0x0100. So Linux swap is 0x82 in MBR and 0x8200 in gdisk 🐚 It's not a perfect one-to-one, though. For example, all the varieties of FAT and NTFS partitions map to a single GPT code (entered as 0x0700 in sgdisk). Some OSes use one MBR code but lots more GPT codes, so sgdisk just adds code numbers in order: 0xa500 for a FreeBSD disklabel, 0xa501 for FreeBSD boot, 0xa502 for FreeBSD swap, and so on 🌈 These two-byte codes are unique to gdisk and sgdisk. And you don't need to give this option a valid disk device filename 🫶
• -m, --gpttombr — converts a disk from GPT to MBR form 🔁 This option takes one to four partition numbers, separated by colons, as arguments. Their type codes are the GPT fdisk type codes divided by 0x0100. If you need the active/bootable flag set, do that in another program, like fdisk. The gdisk program has extra MBR conversion options. You can't convert more than four partitions from GPT to MBR form, and you also can't convert partitions that start above the 2TiB mark or that are bigger than 2TiB 🚫
• -n, --new=partnum:start:end — creates a new partition 🆕 You enter a partition number, a starting sector, and an ending sector. Both start and end can be absolute sector numbers, or positions measured in kibibytes (K), mebibytes (M), gibibytes (G), tebibytes (T), or pebibytes (P). For example, 40M means a position 40MiB from the start of the disk 📍 You can also go relative to the start or end of the default range by putting a + or - in front of the number. So +2G is a point 2GiB after the default start sector, and -200M is a point 200MiB before the last available sector 🧭 A start or end value of 0 gives you the default, which is the start of the largest available block for the start sector, and the end of that same block for the end sector. A partnum value of 0 makes the program use the first available partition number. Later uses of the -A (--attributes), -c (--change-name), -t (--typecode), and -u (--partition-guid) options can also use 0 to refer to that same partition 🎯
• -N, --largest-new=num — creates a new partition that fills the largest available block of space on the disk 🧁 If you want to tweak the alignment, you can use the -a (--set-alignment) option. A num value of 0 makes the program use the first available partition number. Later uses of the -A (--attributes), -c (--change-name), -t (--typecode), and -u (--partition-guid) options can also use 0 to refer to the same partition 💅
• -o, --clear — wipes out all partition data 🧼 That includes the GPT header data, all partition definitions, and the protective MBR. Heads up: like most operations, this one will fail on a damaged disk. If you want to prep a disk you know is damaged for GPT use, wipe it with -Z first and then partition it normally 🛠️ This option works even if the disk's original partition table is bad, but most other options on the same command line will be ignored 😤
• -O, --print-mbr — displays a basic MBR partition summary 📊 It includes partition numbers, starting and ending sector numbers, partition sizes, MBR partition type codes, and partition names. This is mainly useful for diagnosing partition table problems, especially on disks with hybrid MBRs 🔍

✨ OPTIONS ✨ (the glow-up continues)

• -p, --print — 🖨️ Shows the basic GPT partition summary. You get partition numbers, starting and ending sector numbers, partition sizes, sgdisk's partition type codes, and partition names. Want more deets? Use the -i (--info) option 💅
• -P, --pretend — 🫣 Pretend mode! sgdisk alters the in-memory GPT data structures based on your other parameters, but nothing actually gets written to disk. Totally safe to test your moves ✨
• -r, --transpose — 🔀 Swaps two partitions' entries in the partition table. One or both can be empty, though swapping two empty partitions is pointless, bestie 💀. For example, if partitions 1-4 exist, transposing 1 and 5 gives you a table numbered 2-5. The disk space stays exactly where it is. Only the order in the table changes 🦋
• -R, --replicate=second_device_filename — 👯 Copies the main device's partition table onto the second device you name. The copy is an exact clone, GUIDs and all! If the new disk needs its own unique GUIDs, use the -G option on it 🫶
• -s, --sort — 🧹 Sorts the partition entries. GPT partition numbers don't have to match the physical order on the disk, but if you want them to match, this is your option. Heads up: some partitioning tools sort partitions every time they make changes. Those changes show up in your device filenames, so you might need to edit /etc/fstab if you use this option ⚠️
• -t, --typecode=partnum:{hexcode|GUID} — 🏷️ Changes one partition's type code. Pass in either a two-byte hexadecimal number (the one described earlier) or a fully-specified GUID, like EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 🌈
• -T, --transform-bsd=partnum — 🔄 Turns BSD partitions into GPT partitions. This works on BSD disklabels that live inside GPT (or converted MBR) partitions. The converted type codes will probably need manual fixing 🛠️. sgdisk tries to convert BSD disklabels on the main disk when it launches, but that conversion can easily produce first and/or last partitions that are unusable 😭. There are so many BSD variants that sgdisk is way more likely to fail on a BSD disklabel than on an MBR conversion, so keep that in mind 🙈
• -u, --partition-guid=partnum:guid — 🆔 Sets the unique GUID for one partition. Use a complete GUID, or R for a random one 🎲
• -U, --disk-guid=guid — 💿 Sets the GUID for the whole disk. Again, a complete GUID or R for random 🎲
• --usage — 📝 Prints a quick summary of the available options ✨
• -v, --verify — 🕵️‍♀️ Checks the disk for problems like incorrect CRCs and mismatched main and backup data. Heads up though: it doesn't auto-fix most issues. For that, you'll need the options on the recovery & transformation menu 🔧. If everything checks out, it shows you a summary of unallocated disk space. This works even if the disk's original partition table is busted, but most other options on the same command line get ignored 🥲
• -V, --version — 🔖 Shows the program version info. You don't need to give a device filename for this one 💜
• -z, --zap — 💥 Zaps (destroys) the GPT data structures and then exits. This is your move if you want to repartition a GPT disk with fdisk or some other GPT-unaware program 🫠. It only nukes the GPT stuff and leaves the MBR intact, which makes it handy for wiping GPT data after a disk was repartitioned for MBR with a GPT-unaware utility. BUT there's a risk it'll damage boot loaders, or even the start of the first or end of the last MBR partition. And if you use it on a valid GPT disk, the MBR will be left with an inappropriate EFI GPT (0xEE) partition definition, which you'll need to delete with another utility 🙃
• -Z, --zap-all — 🌪️ Zaps (destroys) both the GPT and MBR data structures and then exits. It works a lot like -z, but since it wipes the MBR too, it's the better pick if you're about to repartition the disk afterwards. It's completely unsuitable if you've already repartitioned the disk 🚫
• -?, --help — 🆘 Prints a summary of options 🫶

---

👑 RETURN VALUES 👑

sgdisk returns different values depending on how things go:

• 0 — ✅ Normal program execution, slay
• 1 — 🤏 Too few arguments
• 2 — 📖 An error occurred while reading the partition table
• 3 — 🚫 Non-GPT disk detected, there's no -g option, and the operation needs a write action
• 4 — 💾 An error prevented saving changes
• 5 — ⌨️ An error occurred while reading standard input (this should never happen with sgdisk, but it might with gdisk)
• 8 — 👯 The disk replication operation (-R) failed

---

🐛 BUGS 🐛

Okay, real talk, here are the known bugs and limitations 🥺

• The program only compiles correctly on Linux, FreeBSD, and Mac OS X. Linux versions for x86-64 (64-bit), x86 (32-bit), and PowerPC (32-bit) have been tested, and the x86-64 version has gotten the most testing 💻
• The FreeBSD version can't write partition table changes to a disk while existing partitions on that disk are mounted. (Honestly, this same problem shows up with lots of other FreeBSD utilities, like gpt, fdisk, and dd 😩.) You can get around this by typing sysctl kern.geom.debugflags=16 at a shell prompt 🔓
• The fields that show the start and end sector numbers for partitions in the -p option are 14 characters wide. That works out to a limit of about 45 PiB. On bigger disks, the displayed columns will go out of alignment 📏
• The program can only load up to 128 partitions (4 primary partitions and 124 logical partitions) when converting from MBR format. You can raise this limit by changing the #define MAX_MBR_PARTS line in the basicmbr.h source code file and recompiling. Just know that a change like that needs a larger-than-normal partition table 🧐. (The 128 limit was picked because it equals the 128 partitions supported by the most common partition table size.)
• MBR conversion sometimes fails because there isn't enough space at the start or (more commonly) the end of the disk. Resizing the partition table (using the s option in the experts' menu) can sometimes fix this 🪄. In extreme cases, though, you might need to resize a partition with GNU Parted or a similar tool before converting with gdisk 😤
• MBR conversions only work if the disk has correct LBA partition descriptors. These should be there on any disk over 8 GiB in size, or on smaller disks partitioned with anything other than very ancient software 🦕
• BSD disklabel support can create first and/or last partitions that overlap with the GPT data structures. Sometimes you can fix that by adjusting the partition table size, but in extreme cases the affected partition(s) may need to be deleted 💔
• BSD disklabel structures are super variable, so converting from this form can be unreliable. Partitions may get dropped, converted in a way that overlaps other partitions, or converted with incorrect start or end values. Use this feature with caution!! ⚠️
• Booting after converting an MBR or BSD disklabel disk will probably be messed up. Sometimes reinstalling a boot loader fixes it, but other times you may need to switch boot loaders entirely 🥀. Except on EFI-based platforms, Windows (through at least Windows 7 RC) doesn't boot from GPT disks. Your only options might be creating a hybrid MBR (using the h option on the recovery & transformation menu) or ditching GPT for MBR 🫠

---

🎀 AUTHORS 🎀

Primary author: Roderick W. Smith (rodsmith@rodsbooks.com) 👑

Contributors:

• Yves Blusseau (1otnwmz02@sneakemail.com) 🌸
• David Hubbard (david.c.hubbard@gmail.com) 🌸
• Justin Maggard (justin.maggard@netgear.com) 🌸
• Dwight Schauer (das@teegra.net) 🌸
• Florian Zumbiehl (florz@florz.de) 🌸

---

🔗 SEE ALSO 🔗

cfdisk(8), cgdisk(8), fdisk(8), gdisk(8), mkfs(8), parted(8), sfdisk(8), fixparts(8).

https://en.wikipedia.org/wiki/GUID_Partition_Table

https://developer.apple.com/technotes/tn2006/tn2166.html

https://www.rodsbooks.com/gdisk/

---

🦋 AVAILABILITY 🦋

The sgdisk command is part of the GPT fdisk package and is available from Rod Smith 💖

---

✨ Brought to you by Roderick W. Smith's version 1.0.10 of sgdisk, so cute and so reliable. Go partition something gorgeous, bestie 💅🫶🌈