Last Web page update: 4/18/2022, referencing GPT fdisk version 1.0.9
This Web page, and the associated software, is provided free of charge and with no annoying outside ads; however, I did take time to prepare it, and Web hosting does cost money. If you find GPT fdisk or this Web page useful, please consider making a small donation to help keep this site up and running. Thanks!
Donate $1.00 | Donate $2.50 | Donate $5.00 | Donate $10.00 | Donate $20.00 | Donate another value |
Note: This page is part of the documentation for my GPT fdisk program.
GPT fdisk consists of three programs:
A fourth tool, FixParts, is part of the GPT fdisk source package but is different enough that I distribute its binaries separately. (Many Linux distributions package all four programs together in a package called gdisk, though.) This page documents use of the cgdisk tool. Separate pages provide similar documentation for gdisk and sgdisk, A gdisk Walkthrough and An sgdisk Walkthrough.
The GPT fdisk package includes a man page that documents the cgdisk program in the usual way. If you want to read up on all its options, please refer to that document. This page takes a different approach: It walks you through some common operations, explaining each one.
You must launch cgdisk with administrative privileges on all platforms except when editing disk image files or, on some systems, removable disks. Under Linux, FreeBSD, or macOS, this is done by logging in as the root user, using su to acquire root privileges, or using the sudo utility to launch cgdisk. Under Windows, you can right-click the Command Prompt program and select the "Run as Administrator" option, then use the resulting window to run cgdisk.
You launch cgdisk in much the same way as cfdisk, although cgdisk supports no command-line arguments except for the device specification. This varies from one OS to another:
This walkthrough uses as a starting point the partitioning of a 14.6 GiB USB flash drive so that it contains three partitions: One FAT partition for data exchange among multiple OSes, one ext4fs partition for use by Linux alone, and one HFS+ partition for use by macOS. This scenario is admittedly somewhat artificial, since most people don't use USB flash drives in this way; but this is similar to what you might do when setting up a hard disk for use by multiple OSes, or perhaps even one OS.
The starting point for this walkthrough is a drive with a single FAT partition in an MBR partition table. This starting point illustrates what happens when you start cgdisk on a disk with an existing MBR partition table:
# cgdisk /dev/sdf Warning! Non-GPT or damaged disk detected! This program will attempt to convert to GPT form or repair damage to GPT data structures, but may not succeed. Use gdisk or another disk repair tool if you have a damaged GPT disk. Press any key to continue....
This example demonstrates the warning message that cgdisk displays when it encounters a non-GPT disk or a disk with damaged GPT data structures. In this case, this warning is normal, but if you were launching the program on a healthy GPT disk, you should not see this warning. Like other GPT fdisk programs, cgdisk automatically converts MBR or BSD disks to GPT form, but it warns you of this fact by displaying the preceding warning. A second warning appeared on the disk I used for testing:
Warning! Problems found on disk! Use the Verify function to learn more. Using gdisk or some other program may be necessary to repair the problems. Press any key to continue....
This particular warning appeared because the existing partition was too big—it overlapped with the backup GPT data structures at the end of the disk. If you want to completely erase the partitions on the disk (as in this walkthrough), this isn't a problem; but if you see such a message on an existing GPT disk, you should heed the warning and investigate the problem before proceeding. The Repairing GPT Disks page describes some common GPT repair scenarios.
Once you've cleared the warnings, the main cgdisk menu appears:
cgdisk 1.0.9 Disk Drive: /dev/sdf Size: 30720000, 14.6 GiB Part. # Size Partition Type Partition Name ---------------------------------------------------------------- 1007.0 KiB free space 1 14.6 GiB Microsoft basic data Microsoft basic data [ Align ] [ Backup ] [ Help ] [ Load ] [ New ] [ Quit ] [ Verify ] [ Write ] Create new partition from free space
The display is broken into three main sections:
With the existence of this single partition as (presumably) sufficient identification that this is the disk you want to modify, selecting the partition with the arrow keys and picking the Delete command deletes the partition. You can either use the left or right arrow key to select Delete and then press Enter to do the deed, or press the D key on the keyboard. Either way, the partition will be deleted, and in its place, cgdisk displays free space.
At this point you presumably want to begin adding your new partitions. As with cfdisk, you can use New to do this task (this option appears when you select free space in the partition list). cgdisk asks you for four pieces of information:
First sector (2048-30719966, default = 2048): Size in sectors or {KMGTP} (default = 30715904): 4G Current type is 8300 (Linux filesystem) Hex code or GUID (L to show codes, Enter = 8300): 0700 Current partition name is '' Enter new partition name, orto use the current name: Shared data
In this example, I've created a partition that begins at sector 2048, that's 4 GiB in size, that has a partition type code of 0x0700, and that has a name of Shared data. Most of this information is self-explanatory, but partition type codes require explanation. In GPT, partitions are assigned codes to signify the filesystem or other type of data they contain. These codes are 32-byte GUIDs, which are awkward to remember and enter. Therefore, the GPT fdisk programs, including cgdisk, use a 2-byte (4-character hexadecimal) code for quicker entry. The most common of these codes are based on the equivalent MBR codes, but multiplied by 0x0100. Thus, the MBR code 0x07 (for NTFS) becomes the GPT fdisk code 0x0700. If you don't recall the code, you can view a list of codes by typing L at the code entry prompt and, if desired, filter the list by typing a search string:
Hex code or GUID (L to show codes, Enter = 8300): L Type search string, orto show all codes: data 0700 Microsoft basic data 4200 Windows LDM data 4201 Windows LDM metadata a005 Android metadata a008 Android data a03a Android user data a200 Atari TOS basic data a580 Midnight BSD data c001 HP-UX data e900 Veracrypt data f101 Fuchsia durable mutable encrypted f103 Fuchsia factory ro system data f104 Fuchsia factory ro bootloader data f106 Fuchsia verified boot metadata (sl f10a Fuchsia Data f115 Fuchsia verified boot metadata (A) f116 Fuchsia verified boot metadata (B) f117 Fuchsia verified boot metadata (R)
The search/filter operation is case-sensitive. If you don't search/filter the list, you'll discover it's quite long! You may find that the software changes your starting sector values. See the "Partitioning Advice" page for details on why this is done.
The partition list is now updated to show the new partition, plus two remaining sections of free space:
cgdisk 1.0.9 Disk Drive: /dev/sdf Size: 30720000,, 14.6 GiB Part. # Size Partition Type Partition Name ---------------------------------------------------------------- 1007.0 KiB free space 1 4.0 GiB Microsoft basic data Shared data 10.6 GiB free space [ Align ] [ Backup ] [ Help ] [ Load ] [ New ] [ Quit ] [ Verify ] [ Write ] Create new partition from free space
The small 1007 KiB free space area exists because of partition alignment issues. Although it's possible to create a partition in this space, doing so is usually inadvisable. I'll create two new partitions in this space:
First sector (8390656-30719966, default = 8390656): Size in sectors or {KMGTP} (default = 22327296): 6G Current type is 8300 (Linux filesystem) Hex code or GUID (L to show codes, Enter = 8300): Current partition name is '' Enter new partition name, orto use the current name: Linux data First sector (20973568-30719966, default = 20973568): Size in sectors or {KMGTP} (default = 9744384): Current type is 8300 (Linux filesystem) Hex code or GUID (L to show codes, Enter = 8300): af00 Current partition name is '' Enter new partition name, or to use the current name: HFS+ data
The second partition, which will hold a Linux ext4 filesystem, receives the 0x8300 type code. For the final partition, I used the default partition size rather than enter a value explicitly; and I gave it a 0xaf00 type code, which flags it with the GUID for macOS HFS+ data.
The final result looks like this:
cgdisk 1.0.9 Disk Drive: /dev/sdf Size: 30720000, 14.6 GiB Part. # Size Partition Type Partition Name ---------------------------------------------------------------- 1007.0 KiB free space 1 4.0 GiB Microsoft basic data Shared data 2 6.0 GiB Linux filesystem Linux data 3 4.6 GiB Apple HFS/HFS+ HFS+ data 1007.5 KiB free space [ Align ] [ Backup ] [ Delete ] [ Help ] [ Info ] [ Load ] [ naMe ] [ Quit ] [ Type ] [ Verify ] [ Write ] Change the filesystem type code GUID
cgdisk creates a short gap at the end of most disks, so as to keep the final partition a multiple of the alignment length. This is done to keep the LUKS2 disk encryption tools happy. If you dislike this free space, you can change the alignment value via the Align option; but I recommend doing so only for the final partition, and only if you're not using LUKS2 on that partition.
Before saving your changes, you may want to verify that there are no glaring problems with the GPT data structures. You can do this with the Verify command, which produces a report like this:
No problems found. 4029 free sectors (2.0 MiB) available in 2 segments, the largest of which is 2015 (1007.5 KiB) in size.
In this case, only the two small chunks of free space at the start and end of the disk are available for allocation and no problems were found. If cgdisk found problems, such as overlapping partitions or mismatched main and backup partition tables, it would report them here. Of course, cgdisk includes safeguards to ensure that you can't create such problems yourself. The Verify option's sanity checks are intended to help you spot problems that might result from data corruption.
If problems had been detected, you might be able to correct them using various options on the gdisk recovery & transformation menu. Because cgdisk is intended to be a user-friendly tool for less technically-inclined users rather than a thorough data-repair tool, cgdisk omits the repair and other advanced options of gdisk. The "Repairing GPT Disks" page describes use of gdisk's recovery options in more detail.
With the partitions defined and verified, use Write to write the partition table to disk. (Up until now, the changes have existed only in memory.) The program asks for verification:
Are you sure you want to write the partition table to disk? (yes or no): Warning!! This may destroy data on your disk!
You must type yes or no to this prompt. Single-letter responses and other variants won't be accepted. The main menu will reappear when the operation finishes.
Note for FreeBSD users: A limitation of the FreeBSD version of cgdisk is that it can't ordinarily write to a disk if any partitions from that disk are mounted. If you want to change your boot disk, you'll need to do so from an emergency system or type sysctl kern.geom.debugflags=16 prior to launching cgdisk.
Additional options include the following:
Some of these options are meaningful, and available, only when you've selected a partition (rather than free space) in the partition display.
Once you're done making changes, you can select Quit to exit from cgdisk. Be sure to use Write to save your changes first, though, unless of course you want to abandon them!
You're now back at your shell prompt. Because cgdisk doesn't create filesystems, you'll need to do that at your shell prompt. In the case of the 3-partition disk in this example, you can create two filesystems in Linux:
# mkdosfs /dev/sdf1 # mkfs -t ext4 /dev/sdf2
These commands work just as they would on MBR partitions. The example disk's third partition, which is intended for use in macOS, may be better formatted in that OS than in Linux, although a Linux tool for doing the job, newfs_hfs or mkfs.hfsplus, is available.
Caution: If cgdisk reports that the kernel is still using the old partition table, do not try to create filesystems on or otherwise use your new partitions until you've rebooted! Your new filesystem may be written to the wrong partition (possibly one with valuable data) or written to a location on the disk where you won't be able to find it.
Go on to "An sgdisk Walkthrough"
Return to "GPT fdisk" main page
copyright © 2009–2022 by Roderick W. Smith
If you have problems with or comments about this web page, please e-mail me at rodsmith@rodsbooks.com. Thanks.
Return to my main web page.