A gdisk Walkthrough

by Rod Smith, rodsmith@rodsbooks.com

Last Web page update: 9/10/2011, referencing GPT fdisk version 0.7.2

I'm a technical writer and consultant specializing in Linux technologies. 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
Donate with PayPal
Donate with PayPal
Donate with PayPal
Donate with PayPal
Donate with PayPal
Donate with PayPal

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 it's often distributed separately. This page documents use of the gdisk tool. Separate pages provide similar documentation for cgdisk and sgdisk, A cgdisk Walkthrough and An sgdisk Walkthrough.

The GPT fdisk package includes a man page that documents the gdisk 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.

This walkthrough uses as a starting point the partitioning of a 7.5 GiB USB flash drive so that it contains three partitions: One FAT partition for data exchange among multiple OSes, one ext3fs partition for use by Linux alone, and one UFS partition for use by FreeBSD. 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 is a drive with a single FAT partition in an MBR partition table. This starting point illustrates what happens when you start gdisk on a disk with an existing MBR partition table:

# gdisk /dev/disk1
GPT fdisk (gdisk) version 0.7.2

Partition table scan:
  MBR: MBR only
  BSD: not present
  APM: not present
  GPT: not present


***************************************************************
Found invalid GPT and valid MBR; converting MBR to GPT format.
THIS OPERATON IS POTENTIALLY DESTRUCTIVE! Exit by typing 'q' if
you don't want to convert your MBR partitions to GPT format!
***************************************************************


Command (? for help):

You must launch gdisk with administrative privileges on all platforms except when editing disk image files or, on some systems, removable disks. Under Linux, FreeBSD, or OS X, this is done by logging in as the root user, using su to acquire root privileges, or using the sudo utility. Under Windows, you can right-click the Command Prompt program and select the "Run as Administrator" option, then use the resulting window to run gdisk.

You launch gdisk in much the same way as fdisk, although gdisk supports very few command-line arguments. (You may pass it the -l option to see the partition table and then quit, but that's it.) You must know the name of the device file that's used to access the disk. This varies from one OS to another:

When gdisk starts, it performs a scan for four types of existing partition tables and displays the results. MBR is the common Master Boot Record partitioning system; BSD is the Berkeley Standard Distribution (BSD) disklabel system used on some computers that run a BSD (FreeBSD, OpenBSD, etc.); APM is the Apple Partition Map used on 680x0- and PowerPC-based Macintoshes; and GPT is of course the GUID Partition Table. The BSD and APM scans report either present or not present, but GPT can report three states (present, not present, or damaged), and there are four MBR states (MBR only, protective, hybrid, or not present). The normal state for an MBR-only disk is as shown above, and the normal state for a GPT disk is MBR: protective and GPT: present. Hybrid MBRs (described on my Hybrid MBRs page) change the MBR state to hybrid. Other combinations are possible, some of which indicate that a disk has been re-partitioned for a new partitioning system without completely erasing the old partition table.

When starting gdisk on a disk with existing MBR or BSD disklabel partitions and no GPT, the program displays a message surrounded by asterisks about converting the existing partitions to GPT. This is intended to scare you away if you launch gdisk on the wrong disk by accident or if you don't know what you're doing. If you launch the program on an MBR disk, Windows users will see a warning about Windows' inability to boot from or read GPT, depending on the Windows version. You must explicitly respond to this warning before proceeding. This is a deliberate "speed bump" to keep inexperienced Windows users from accidentally damaging their boot disks.

The Command (? for help): prompt is taken straight from Linux fdisk, except that GPT fdisk uses ? as the prompt for help, whereas fdisk uses m. If you type ?, you'll see a list of available commands:

Command (? for help): ?
b	back up GPT data to a file
c	change a partition's name
d	delete a partition
i	show detailed information on a partition
l	list known partition types
n	add a new partition
o	create a new empty GUID partition table (GPT)
p	print the partition table
q	quit without saving changes
r	recovery and transformation options (experts only)
s	sort partitions
t	change a partition's type code
v	verify disk
w	write table to disk and exit
x	extra functionality (experts only)
?	print this menu

fdisk users will recognize many of these commands, such as d, n, and p. Although some of these don't work in exactly the same way as in fdisk, most of them are very similar. For instance, suppose you want to verify that you're working on the disk you think you're working on and then delete the partition:

Command (? for help): p
Disk /dev/disk1: 15654912 sectors, 7.5 GiB
Disk identifier (GUID): 5BECF16E-AB31-41FA-B686-50A0A6E264F5
Partition table holds up to 128 entries
First usable sector is 34, last usable sector is 15654878
Partitions will be aligned on 1-sector boundaries
Total free space is 38 sectors (19.0 KiB)

Number  Start (sector)    End (sector)  Size       Code  Name
   1              63        15654869   7.5 GiB     0700  Microsoft basic data

Command (? for help): d
Using 1

Command (? for help): 

The disk data shown by p is a bit different from fdisk's, but it's similar. One salient point is that, because GPT knows nothing about CHS geometry, gdisk measures all partitions in sectors (aka blocks). The original converted MBR partition begins at sector 63 and ends at sector 15,654,869.

The Code column of the output shows the partition type code. Because GPT employs a 16-byte GUID number for storing partition type codes, displaying this raw code would be both space-consuming and difficult for people to parse. Thus, gdisk translates the GUID code into a variant of MBR type codes. In particular, the codes used by gdisk are the MBR codes multiplied by hexadecimal 0x0100, and displayed in hexadecimal. The 0x0700 code shown above is therefore equivalent to an MBR code of 0x07, which is the code for HPFS/NTFS.

"But wait," you say, "I thought the disk had a FAT partition!" Indeed it does. Windows uses a single GUID code for all its data partitions, be they FAT or NTFS. Until recently, the same code has been used in Linux for its data partitions. (More on this shortly....) Thus, in this case several different MBR codes are all translated into a single GPT GUID code. GPT fdisk uses, somewhat arbitrarily, the 0x0700 code (or more precisely, EBD0A0A2-B9E5-4433-87C0-68B6B72699C7) for all of these.

The Name column displays a free-form text string that you can modify. Starting with version 0.4.0, gdisk places the name associated with the partition type code in this field when it creates or converts partitions, but you can change this default, as described shortly. Note that GPT fdisk accesses the GPT data structure's name for a partition. Most filesystems also support a name that's part of the filesystem's data structure. The two can match, but they don't have to, and GPT fdisk makes no attempt to synchronize the two names. Confusingly, some partitioning tools, including GParted under Linux and both Disk Utility and diskutil under OS X, display the filesystem name and hide the GPT name.

With the existence of this single partition as (presumably) sufficient identification that this is the disk you want to modify, the d command deletes the partition. Since only one partition exists, gdisk doesn't prompt you for a number; it just responds Using 1 and then displays another command prompt.

At this point you presumably want to begin adding your new partitions. As with fdisk, you can use n to do this task:

Command (? for help): n
Partition number (1-128, default 1):
First sector (34-15654878, default = 34) or {+-}size{KMGT}:
Last sector (34-15654878, default = 15654878) or {+-}size{KMGT}: +4G
Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300): L
0700 Microsoft basic data  0c01 Microsoft reserved    2700 Windows RE          
4200 Windows LDM data      4201 Windows LDM metadata  7501 IBM GPFS            
7f00 ChromeOS kernel       7f01 ChromeOS root         7f02 ChromeOS reserved   
8200 Linux swap            8300 Linux filesystem      8301 Linux reserved      
8e00 Linux LVM             a500 FreeBSD disklabel     a501 FreeBSD boot        
a502 FreeBSD swap          a503 FreeBSD UFS           a504 FreeBSD ZFS         
a505 FreeBSD Vinum/RAID    a800 Apple UFS             a901 NetBSD swap         
a902 NetBSD FFS            a903 NetBSD LFS            a904 NetBSD concatenated 
a905 NetBSD encrypted      a906 NetBSD RAID           ab00 Apple boot          
af00 Apple HFS/HFS+        af01 Apple RAID            af02 Apple RAID offline  
af03 Apple label           af04 AppleTV recovery      be00 Solaris boot        
bf00 Solaris root          bf01 Solaris /usr & Mac Z  bf02 Solaris swap        
bf03 Solaris backup        bf04 Solaris /var          bf05 Solaris /home       
bf06 Solaris alternate se  bf07 Solaris Reserved 1    bf08 Solaris Reserved 2  
bf09 Solaris Reserved 3    bf0a Solaris Reserved 4    bf0b Solaris Reserved 5  
c001 HP-UX data            c002 HP-UX service         ef00 EFI System          
ef01 MBR partition scheme  ef02 BIOS boot partition   fd00 Linux RAID
Hex code or GUID (L to show codes, Enter = 8300): 0700
Changed system type of partition to 'Linux/Windows data'

In this example, I pressed the Enter key to accept the default partition number and first sector values. The default starting sector is at the start of the largest contiguous block of free space, which in this case is the beginning of all free space. I then typed +4G to create a 4 GiB partition. I typed L to see a list of partition type codes for this first partition, just so you could see them. Since the first partition should be a FAT partition, I opted to give it a 0x0700 type code, which gdisk translates into the correct GUID.

You may find that the software changes your starting sector values. See the "Partitioning Advice" page for details on why this is done.

Starting with gdisk 0.4.1, partition locations and sizes can be entered in either absolute or fully relative form. In absolute form, you enter an absolute location or end point in sectors (or KiB, MiB, GiB, or TiB), as in 34 for sector 34 or 4M for the sector that corresponds to the 4MiB position on the disk. Relative values are specified by preceding the number with a plus sign (+) or minus sign (-), in which case the value is taken as relative to the start or end, respectively, of the free disk space area noted in the prompt. You can use this feature to create partitions with gaps between them, or to leave just enough space after a partition to create another one of a given size. For instance, you can specify +128M as the first sector to produce a 128MiB gap between the partition you're creating and the previous one; or you can specify -1G as the last sector to fill all but 1GiB of the contiguous free space.

With that task done, it's now time to create two more partitions, but these will have to be smaller:

Command (? for help): n
Partition number (2-128, default 2):
First sector (8388642-15654878, default = 8388642) or {+-}size{KMGT}:
Last sector (8388642-15654878, default = 15654878) or {+-}size{KMGT}: +2G
Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300): 8300
Changed system type of partition to 'Linux filesystem'

Command (? for help): n
Partition number (3-128, default 3):
First sector (12582946-15654878, default = 12582946) or {+-}size{KMGT}:
Last sector (12582946-15654878, default = 15654878) or {+-}size{KMGT}:
Current type is 'Linux filesystem'
Hex code or GUID (L to show codes, Enter = 8300): a503
Changed system type of partition to 'FreeBSD UFS'

The second partition, which will hold a Linux ext3 filesystem, receives the new (as of gdisk 0.7.2) 0x8300 type code. Prior to June of 2011, no official Linux filesystem GUID type code existed; Linux partitions typically took the same code as Windows partitions. This can cause problems, though, because Windows sees the Linux partitions as unformatted Windows partitions, and offers to format them—something you don't want to do! The new 0x8300 type code (or 0FC63DAF-8483-4772-8E79-3D69D8477DE4) avoids that problem, so I recommend you use it on Linux partitions. For the final partition, I used the default end partition number rather than enter a value explicitly; and I gave it a 0xa503 type code, which flags it with the GUID for FreeBSD UFS data.

You can now examine the partitions you've created:

Command (? for help): p
Disk /dev/disk1: 15654912 sectors, 7.5 GiB
Disk identifier (GUID): 5BECF16E-AB31-41FA-B686-50A0A6E264F5
Partition table holds up to 128 entries
First usable sector is 34, last usable sector is 15654878
Partitions will be aligned on 1-sector boundaries
Total free space is 0 sectors (0 bytes)

Number  Start (sector)    End (sector)  Size       Code  Name
   1              34         8388641   4.0 GiB     0700  Microsoft basic data
   2         8388642        12582945   2.0 GiB     8300  Linux filesystem
   3        12582946        15654878   1.5 GiB     A503  FreeBSD UFS

The Name column holds default names, but you can assign your partitions more descriptive names using the c command:

Command (? for help): c
Partition number (1-3): 1
Enter name: Shared (FAT) data

Command (? for help): c
Partition number (1-3): 2
Enter name: Linux ext3fs data

Command (? for help): p
Disk /dev/disk1: 15654912 sectors, 7.5 GiB
Disk identifier (GUID): 5BECF16E-AB31-41FA-B686-50A0A6E264F5
Partition table holds up to 128 entries
First usable sector is 34, last usable sector is 15654878
Partitions will be aligned on 1-sector boundaries
Total free space is 0 sectors (0 bytes)

Number  Start (sector)    End (sector)  Size       Code  Name
   1              34         8388641   4.0 GiB     0700  Shared (FAT) data
   2         8388642        12582945   2.0 GiB     8300  Linux ext3fs data
   3        12582946        15654878   1.5 GiB     A503  FreeBSD UFS

You can now tell by using the p command what the partition's purpose is. (GNU Parted and many other tools also display partitions' names.) Partition names may theoretically contain any legal UTF-16 character, at least on Linux, FreeBSD, and OS X, and if the binary you're using was compiled with Unicode support. In practice, though, you must have your locale set correctly and you must be using a font that supports the characters you plan to use.

Caution: At least as of version 3.0, GNU Parted does not properly support UTF-16 names, and in fact some such names can cause it to crash! I'm confident that GPT fdisk's support is correct because OS X's diskutil can read its UTF-16 names just fine.

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 v command:

Command (? for help): v
No problems found. 0 free sectors (0 bytes) available in 0
segments, the largest of which is 0 sectors (0 bytes) in size

In this case, every available byte on the disk is allocated to partitions and no problems were found. If free space were available for partition creation, you'd see how much was available. If gdisk found problems, such as overlapping partitions or mismatched main and backup partition tables, it would report them here. Of course, gdisk includes safeguards to ensure that you can't create such problems yourself. The v 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 recovery & transformation menu, which is a second menu of options available by typing r:

Command (? for help): r

recovery/transformation command (? for help): ?
b	use backup GPT header (rebuilding main)
c	load backup partition table from disk (rebuilding main)
d	use main GPT header (rebuilding backup)
e	load main partition table from disk (rebuilding backup)
f	load MBR and build fresh GPT from it
g	convert GPT into MBR and exit
h	make hybrid MBR
i	show detailed information on a partition
l	load partition data from a backup file
m	return to main menu
o	print protective MBR data
p	print the partition table
q	quit without saving changes
t	transform BSD disklabel partition
v	verify disk
w	write table to disk and exit
x	extra functionality (experts only)
?	print this menu

The "Repairing GPT Disks" page describes use of this page's recovery options in more detail.

Transformation options enable you to perform partition table transformations that are not handled automatically when the program starts: convert a GPT to MBR (g), create a hybrid MBR (h), or convert BSD disklabels in a container partition into GPT partitions (t). These options are described in more detail on the Converting to GPT and Hybrid MBR pages of this document.

A third menu, the experts' menu, can be accessed by typing x in either the main menu or the recovery & transformation menu:

recovery/transformation command (? for help): x

Expert command (? for help): ?
a       set attributes
c       change partition GUID
d       display the sector alignment value
e       relocate backup data structures to the end of the disk
g       change disk GUID
i       show detailed information on a partition
l       set the sector alignment value
m       return to main menu
n       create a new protective MBR
o       print protective MBR data
p       print the partition table
q       quit without saving changes
r       recovery and transformation options (experts only)
s       resize partition table
v       verify disk
w       write table to disk and exit
z       zap (destroy) GPT data structures and exit
?       print this menu

You can do some low-level edits, such as changing partition or disk GUIDs (c and g, respectively). The z option immediately destroys the GPT data structures, which you should do if you want to re-use a GPT disk using some other partitioning scheme. If these structures aren't erased, some partitioning tools can become confused by the apparent presence of two partitioning systems.

Caution: Version 0.4.2 of gdisk replaced the MBR when using the z option, so if you used fdisk or some other MBR-unaware utility to repartition a GPT disk and then used this option in gdisk to erase the older GPT data structures, you'd lose your new MBR partitions. This is not the case in earlier or later versions of gdisk unless you answer in the affirmative when asked if you want to wipe out the MBR. Nonetheless, if you've already repartitioned using a GPT-unaware tool, you should be cautious; it's possible that the new partitions will occupy some of the space that the older GPT structures once occupied. In this case, GPT fdisk might damage your new partitions.

Generally speaking, the options on both the recovery & transformation menu and the experts' menu shouldn't be used by anything but GPT experts. Non-experts might be forced to use these menus if a disk is damaged, though. Before taking drastic actions, you should use the b main-menu option to create a backup in a file, and store that file on a USB flash drive or some other place that's not on the disk you're modifying. That way, you'll be able to recover your orginal configuration if you damage your partitions.

Once you're done making your changes, be they relatively simple partition creations or recovery from disk damage, you can exit from gdisk. The q command exits without saving your changes, while w writes your changes to disk. Both commands exist on both the main and experts' menus.

Expert command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!

Do you want to proceed? (Y/N): y
OK; writing new GUID partition table (GPT).
The operation has completed successfully.

Note for FreeBSD users: A limitation of the FreeBSD version of gdisk 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 gdisk.

You're now back at your shell prompt. Because gdisk 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/sdc1
# mkfs -t ext3 /dev/sdc2

These commands work just as they would on MBR partitions. The example disk's third partition, which is intended for use in FreeBSD, is better formatted in that OS than in Linux.

Caution: If gdisk 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 "A cgdisk Walkthrough"

Return to "GPT fdisk" main page


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.