CGDISK(8)

💖 NAME 💖

cgdisk - Curses-based GUID partition table (GPT) manipulator 🎀

🧚 SYNOPSIS 🧚

cgdisk [ -a ] device

🌸 DESCRIPTION 🌸

okay so GPT fdisk is a whole family of text-mode programs for making and messing with partition tables 💅 cgdisk is the member of the family with the curses-based user interface, so you get a text-mode menu system to click around in 🦋 It will automatically convert an old-style Master Boot Record (MBR) partition table or a BSD disklabel stored without an MBR carrier partition into the newer Globally Unique Identifier (GUID) Partition Table (GPT) format, or it will just load a GUID partition table if you already have one ✨ The other members of the crew are gdisk (the most feature-rich one, with a non-curses interactive interface 🔥) and sgdisk (driven by command-line options, so it's for experts and scripts 🤓). FixParts is a related program that fixes a limited set of problems on MBR disks 🛠️

for info on MBR vs. GPT, plus GPT terminology and structure, check out the extended GPT fdisk documentation at https://www.rodsbooks.com/gdisk/ or just consult Wikipedia 📚🫶

the cgdisk program has a user interface that's super similar to Linux's cfdisk 💜 but cgdisk is the one that edits GPT partitions. It can also transform MBR partitions or BSD disklabels into GPT partitions, which is lowkey iconic 👑 Just like the original cfdisk, cgdisk doesn't touch your disk structures until you explicitly write them to disk. So if you mess up, you can exit with the Quit option and your partitions stay exactly as they were 🙈✨

ordinarily, cgdisk operates 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 operate on disk image files, which can be either copies of whole disks (made with dd, for instance) or raw disk images used by emulators such as QEMU or VMWare 🌈 Note that only raw disk images are supported. cgdisk cannot work on compressed or other advanced disk image formats, so don't even try 🙅‍♀️

upon start, cgdisk tries to figure out which partition type is in use on the disk. If it finds valid GPT data, it uses it, no questions asked 💅 If it finds a valid MBR or BSD disklabel but no GPT data, it'll attempt to convert the MBR or disklabel into GPT form. (BSD disklabels are likely to have unusable first and/or final partitions, because they overlap with the GPT data structures, though 😭) Upon exiting with the 'w' option, cgdisk replaces the MBR or disklabel with a GPT.

⚠️ this action is potentially dangerous!! Your system may become unbootable, and partition type codes may become corrupted if the disk uses unrecognized type codes. Boot problems are particularly likely if you're multi-booting with any GPT-unaware OS 💀 If you accidentally launch cgdisk on an MBR disk, you can safely exit without making any changes by using the Quit option. Phew 🫶

✨ OPTIONS ✨

okay so bestie, there's only ONE command-line option you can pass besides the device filename, and it's -a 🦋. It changes how partitions and free space get highlighted. Instead of fancy ncurses colours, -a makes cgdisk put a > symbol to the left of whatever you've selected 💅. It's built for limited displays like teletypes and screen readers, so if that's your setup, this one's for you 🫶.

Everything happens in the interactive text-mode menus. The screen is split into two interactive parts:

• Partition display area 🌸, where your partitions and the gaps between them (labelled "free space") get summarised.
• Option selection area 🎀, where the buttons for the main options live.

The very top of the screen is also giving info 👑. It shows the program's name and version number, the device filename for your disk, and the disk's size in both sectors and IEEE-1541 units (GiB, TiB, and so on).

⌨️ Keys ⌨️

These are the keys you use to move around and pick stuff ✨:

• up arrow 🔼 moves the partition selection up by one partition.
• down arrow 🔽 moves the partition selection down by one partition.
• Page Up ⬆️ moves the partition selection up by one screen.
• Page Down ⬇️ moves the partition selection down by one screen.
• right arrow ➡️ moves the option selection to the right by one item.
• left arrow ⬅️ moves the option selection to the left by one item.
• Enter 💖 activates whichever option is currently selected. You can also activate an option by typing the capitalised letter in its name, so typing a activates the Align option 🙈.

If there are more partitions than fit on one screen, you can scroll between screens with the partition selection keys, just like in a text editor 📝.

Heads up: cgdisk is a much more chill, limited version of its sibling gdisk 🥺. If you need partition table recovery, hybrid MBR modification, or other advanced stuff, go check out the gdisk documentation instead.

🌈 Options 🌈

Here are the available options, in all their glory:

• Align 📐 changes the sector alignment value. Disks with more logical sectors than physical sectors (like modern Advanced Format drives), some RAID setups, and lots of SSDs can get performance issues if partitions aren't aligned properly for their internal data structures 😭. On brand-new disks, GPT fdisk tries to align partitions on 1 MiB boundaries (2048-sectors on disks with 512-byte sectors) by default, which keeps performance great across all of these disk types ✨. On pre-partitioned disks, GPT fdisk tries to figure out the alignment value that was used on that disk, but it'll set 8-sector alignment on disks larger than 300 GB even if smaller alignment values get detected 🙃. Either way, you can change it with this option. The alignment value also affects the default end sector when you create a new partition: it gets aligned to one less than a multiple of the alignment value, when possible 🎯. This should keep partitions a multiple of the alignment value in size. Some disk encryption tools need partitions sized to a certain value, usually 4096 bytes, so the default 1 MiB alignment works great for them 🔐.
• Backup 💾 saves your partition data to a backup file. It backs up your current in-memory partition table to a disk file 🗂️. 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. Heads up though: the backup reflects the current in-memory data, so if you launch the program, make changes, and then use this option, the backup will include your changes 👀.
• Delete 🗑️ deletes a partition. It removes the entry from the partition table but leaves the data inside the sectors that were originally allocated to the partition 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 🌿.
• Help 📖 prints brief descriptions of all the options. Iconic.
• Info 🔍 shows detailed partition information. The summary in the partition display area has to leave out a lot of details, like each partition's unique GUIDs and its sector-exact start and end points 🤓. The Info option shows all of that for a single partition.
• Load 📥 loads partition data from a backup file. It's the reverse of Backup 🔄. Just know that restoring partition data from anything other than the original disk is not recommended 💀.
• naMe 🏷️ changes the GPT name of a partition. The name is stored as a UTF-16 string, but properly entering and displaying anything beyond basic ASCII needs the right locale and font support 🌍. Mostly Linux ignores the partition name, though it can matter on some other OSes 🤷‍♀️. GPT fdisk sets a default name based on the partition type code. The GPT partition name is NOT the same as the filesystem name, which is stored in the filesystem's own data structures 🧠. Also, to activate this item by typing its letter, you need to use M, not the more obvious N, because N is taken by the next option....
• New ✨ creates a new partition. You enter a starting sector, a size, a type code, and a name 🎂. The start sector can be a plain sector number, or a position 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 count relative to the start or end of the default range by putting a + in front, like +2G for a point 2GiB after the default start sector 🚀. The size value takes the K, M, G, T, and P suffixes too 💅. Hit Enter with no input and you get the defaults: the start of the largest available block for the start sector, and the full available size for the size 🫶.
• Quit 🚪 leaves the program without saving your changes. Use this if you just wanted to peek at info, or if you messed up and want to back out of everything 🙈.
• Type 🎨 changes a single partition's type code. You enter it as a two-byte hexadecimal number 🔢. You can also type a GUID directly if you have one and cgdisk doesn't recognise it 🪪. Don't know your partition's type code? Type L to see a list of known type codes 📜. You can filter that list with a search string, too: entering linux shows only the type codes whose descriptions include the string Linux 🐧. The search is case-insensitive, so LINUX or linux both work 💜.
• Verify 🔎 checks the disk for a bunch of problems, like incorrect CRCs and mismatched main and backup data 🧐. It does NOT automatically fix most of them, though; for that you need gdisk 🛠️. If no problems are found, this command shows a summary of your unallocated disk space 🌸.
• Write 💖 saves your changes. This is the one you press when you're ready to commit ✅.

🐛 BUGS 🐛

okay so bestie, here's the tea on what's still messy 🫣 Known bugs and limitations include:

• Platforms 💻 — this compiles properly only on Linux, FreeBSD, and Mac OS X. In theory it should build on Windows if the Ncurses library for Windows is installed, but nobody has actually tested that 🙈 On Linux, the x86-64 (64-bit), x86 (32-bit), and PowerPC (32-bit) builds have been tested, and x86-64 got the most love. On FreeBSD, the 32-bit (x86) and 64-bit (x86-64) builds have been tested. On Mac OS X, only the 32-bit build has been tested by the author.
• FreeBSD mounted-disk drama 😤 — on FreeBSD, the program can't write partition table changes to a disk while its existing partitions are mounted. (Honestly, same problem with a bunch of other FreeBSD tools like gpt, fdisk, and dd, so you're not alone 💜) You can get around it by typing sysctl kern.geom.debugflags=16 at a shell prompt.
• The 128-partition ceiling 🧱 — when converting from MBR format, the program can only load up to 128 partitions (4 primary and 124 logical). You can raise that by changing the #define MAX_MBR_PARTS line in the basicmbr.h source code file and recompiling, but heads up: that change means you'll need a bigger-than-normal partition table. (The limit is 128 because that's how many partitions the most common partition table size supports, so it's not random 🎀)
• Conversions can run out of room 🫠 — converting from MBR sometimes fails because there isn't enough space at the start or, more often, the end of the disk. Resizing the partition table with the s option in the experts' menu in gdisk can sometimes fix it. In extreme cases, you may need to resize a partition with GNU Parted or a similar tool before converting with GPT fdisk.
• LBA descriptors have to be legit 🔍 — MBR conversions only work if the disk has correct LBA partition descriptors. Any disk over 8 GiB should have them, and so should smaller disks partitioned with anything other than really ancient software.
• BSD disklabel overlaps 😬 — BSD disklabel support can create first and/or last partitions that overlap the GPT data structures. Sometimes you can fix that by adjusting the partition table size, but in extreme cases the affected partition(s) might have to be deleted.
• BSD disklabel = unpredictable 🎲 — because BSD disklabel structures are super variable, converting from this format can be unreliable. Partitions might get dropped, converted in a way that overlaps other partitions, or come out with wrong start or end values. > Use this feature with caution!
• Booting after conversion might break 🥺 — booting after converting an MBR or BSD disklabel disk is likely to get disrupted. Sometimes reinstalling a boot loader fixes it, but other times you may need to switch boot loaders entirely. Unless you're on an EFI-based platform, Windows through at least Windows 7 doesn't boot from GPT disks. In that case, a hybrid MBR (made with the h option on the recovery & transformation menu in gdisk) or ditching GPT for MBR might be your only options.
• Verify and Type listings go rogue 🙃 — the cgdisk Verify function and the partition type listing you get by typing L in the Type function (or when picking a partition type while creating a new partition) both currently exit ncurses mode. It's a minor cosmetic blemish, not a functionality issue, so it's totally vibey ✨

---

👑 AUTHORS 👑

The primary author, the one who made this whole thing happen, is Roderick W. Smith (rodsmith@rodsbooks.com) 🫶

The contributors who helped make it better are:

• 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 🔗

Go deeper with these bestie-approved reads: cfdisk(8), fdisk(8), gdisk(8), mkfs(8), parted(8), sfdisk(8), sgdisk(8), and fixparts(8) 📚

And for the lore, check out:

• https://en.wikipedia.org/wiki/GUID_Partition_Table
• https://developer.apple.com/technotes/tn2006/tn2166.html
• https://www.rodsbooks.com/gdisk/

---

🌸 AVAILABILITY 🌸

The cgdisk command is part of the GPT fdisk package, and you can grab it from Rod Smith himself 💖

---

Sign-off time 🧚 This page was written by Roderick W. Smith, covers version 1.0.10 of cgdisk, and lives on the CGDISK(8) page of the manual. Stay iconic and keep those partitions in line 💅✨