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 sgdisk tool. Separate pages provide similar documentation for gdisk and cgdisk, A gdisk Walkthrough and A cgdisk Walkthrough.
The GPT fdisk package includes a man page that documents the sgdisk 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.
The sgdisk program relies on the popt library, which is commonly installed on Linux systems and is also available for FreeBSD, macOS, and Windows; however, it's less often installed on these platforms. Therefore, you may find that sgdisk won't compile, or won't work if you've got a binary version of it, until you install popt.
Before beginning, I wish to emphasize the fact that sgdisk is intended for use in scripts or by experts. The program is unforgiving of user error—if you tell it to delete a partition, empty the partition table, or perform some other destructive operation, the program will do so without asking for confirmation. It will immediately save changes to disk, so recovering from an error can be difficult. If you intend to manually partition a disk, I strongly recommend you use gdisk or cgdisk rather than sgdisk, since gdisk and cgdisk are more interactive in nature, warn you when you're about to do something dangerous, and provide the opportunity to back out of any changes you make before saving them to disk.
The sgdisk program provides built-in help in the form of the -? (--help) command, so if you need a reminder of an option name, typing sgdisk -? should give you a clue. Briefer help is available via the --usage option. Typically, you type sgdisk, the names of one or more options and their arguments, and the device filename for a disk device. The most important options are:
| Option | Argument(s) | Purpose | -b or --backup | filename | Save a backup of the disk to the specified file. |
|---|---|---|
| -c or --change-name | partnum:name | Change the name of the specified partition. |
| -d or --delete | partnum | Delete the specified partition. |
| -E or --end-of-largest | none | Display the sector number at the end of the largest empty block of sectors on the disk. |
| -f or --first-in-largest | none | Display the sector number of the start of the largest empty block of sectors on the disk. |
| -F or --first-aligned-in-largest | none | Display the sector number of the first usable sector of the largest empty block of sectors on the disk, after partition alignment is considered. |
| -g or --mbrtogpt | none | Convert an MBR or BSD disklabel disk to GPT format. |
| -i or --info | partnum | Display detailed information on the specified partition. |
| -I or --align-end | none | Align partition end points, as well as beginnings. Sometimes useful if a partition is to be used with LUKS2 encryption. |
| -n or --new | partnum:start:end | Create a new partition, numbered partnum, starting at sector start and ending at sector end. |
| -o or --clear | none | Erase all GPT data structures and create a fresh GPT. |
| -p or --print | none | Display the current partition table. |
| -P or --pretend | none | Perform actions only on in-memory representation; don't save changes to disk. |
| -t or --typecode | partnum:hexcode | Change a partition's GUID type code to the one specified by hexcode. Note that hexcode is a gdisk/sgdisk internal two-byte hexadecimal code. You can obtain a list of codes with the -L option. |
| -v or --verify | none | Verify the integrity of the partition table and report the results. |
| -V or --version | none | Display the version number |
| -z or --zap | none | Zero out all GPT data structures, but leave the MBR intact. Use this option if you want to completely erase the GPT data structures so that the disk can be used as an MBR disk without concern that it might contain stray GPT data; or on a disk that used to be a GPT disk but that was re-partitioned with a GPT-unaware utility, so that the GPT data structures are no longer valid. (FixParts may be a better tool for the latter scenario, though.) | -Z or --zap-all | none | Zero out all GPT and MBR data structures. Use this option if you want to completely erase the GPT data structures so that the disk can be used as an MBR disk without concern that it might contain stray GPT data |
Additional options are documented in the sgdisk man page. The -E, -f, and -F options require a bit of elaboration. These options all work by finding the largest contiguous area of unallocated space on the disk and then returning the numbers of the final (-E), first (-f), and first usable (-F), free sectors in that area. The idea is to facilitate automated creation of partitions by locating where they might reasonably reside, even if there are short gaps between existing partitions. Such gaps can be created by MBR-to-GPT conversions, by sector alignment, or by some OSes' partitioning tools (Apple's Disk Utility creates 128 MiB gaps between partitions, for instance.) If you need to know where a partition will actually begin if you create it with the current partition alignment, use -F; but if you need to know where a partition could begin if alignment were set to 1 sector, use -f.
Some options take a single value as an argument, such as a filename or a partition number (partnum in the preceding table). Other options require compound arguments, with parts separated by colons (:).
Option order is important: Actions are performed in the order in which they are specified on the command line. This can have implications for the validity of certain commands. For instance, changing a partition's name and then deleting it is legal, but deleting a partition and then changing its name is not legal. sgdisk will refuse to save changes if you try the latter—but you shouldn't count on sgdisk catching such egregious errors.
This walkthrough demonstrates several methods of creating partitions and obtaining information on existing partitions. To begin, you must know the name of the device file that's used to access the disk. This name varies depending on the OS and type of disk:
As a first step in this walkthrough, you may want to review the partitions that exist on a disk. As a starting point, this walkthrough uses a 14.6 GiB USB flash drive with a single FAT partition as an example:
# sgdisk -p /dev/sdf *************************************************************** Found invalid GPT and valid MBR; converting MBR to GPT format in memory. *************************************************************** Warning! Secondary partition table overlaps the last partition by 33 blocks! You will need to delete this partition or resize it in another utility. Disk /dev/sdf: 30720000 sectors, 14.6 GiB Model: STORE N GO Sector size (logical/physical): 512/512 bytes Disk identifier (GUID): B29DF43E-CA6B-4525-B2A1-8A045A010F1F Partition table holds up to 128 entries Main partition table begins at sector 2 and ends at sector 33 First usable sector is 34, last usable sector is 30719966 Partitions will be aligned on 2048-sector boundaries Total free space is 4029 sectors (2.0 MiB) Number Start (sector) End (sector) Size Code Name 1 2048 30717951 14.6 GiB 0700 Microsoft basic data
sgdisk automatically converts the MBR to GPT form and displays the converted partition. Because the -p option is informational only, changes aren't saved back. The disk could have been converted to GPT by adding the -g option — except for the warning about the secondary partition table overlapping the last partition. This issue is common on MBR disks converted to GPT format, and will necessitate deleting the offending partition. (If that's not appropriate, you'll need to take some other action first, like resizing the partition in another tool.) As this walkthrough intends to delete this partition, this warning isn't an issue.
Suppose you want to replace the one existing partition with three new partitions: A 2 GiB partition for Linux, a 5 GiB shared FAT partition, and a 7 GiB FreeBSD partition. You might begin by deleting the existing partition and creating the Linux partition:
# sgdisk -d 1 -n 1:2048:4196351 -g /dev/sdf *************************************************************** Found invalid GPT and valid MBR; converting MBR to GPT format in memory. *************************************************************** Warning! Secondary partition table overlaps the last partition by 33 blocks! You will need to delete this partition or resize it in another utility. The operation has completed successfully.
The -n option tells sgdisk to create partition #1 beginning at sector 2048 and ending at sector 4196351. The sector-2048 starting point is done for proper alignment, as described on the Partitioning Advice page, and the ending sector number was manually calculated to create a 2 GiB partition. The -g option is necessary to save the changes, since the disk had an MBR configuration initially. As you can see, sgdisk repeated its warnings about having found an MBR partition table and about the overlap of the final partition with the end data, since the earlier call using -p didn't change anything on the disk. After this call, though, it's a GPT disk, but the program didn't print the partition table, since no -p option was included. The default type for a new partition varies from one platform to another. In Linux, it's 8300 (Linux filesystem), so the previous example didn't need to change the partition type. The next one, however, does; it uses the -t option to set the type code to 0700 (Microsoft basic data) for one partition and A503 (FreeBSD UFS) for the other:
# sudo sgdisk -n 2:0:+5G -n 3:0:+7G -t 2:0700 -t 3:a503 /dev/sdf -p Disk /dev/sdf: 30720000 sectors, 14.6 GiB Model: STORE N GO Sector size (logical/physical): 512/512 bytes Disk identifier (GUID): 739CB37E-1201-47C2-9304-036EE67223F0 Partition table holds up to 128 entries Main partition table begins at sector 2 and ends at sector 33 First usable sector is 34, last usable sector is 30719966 Partitions will be aligned on 2048-sector boundaries Total free space is 1359805 sectors (664.0 MiB) Number Start (sector) End (sector) Size Code Name 1 2048 4196351 2.0 GiB 8300 2 4196352 14682111 5.0 GiB 0700 3 14682112 29362175 7.0 GiB A503 The operation has completed successfully.
This example illustrates the use of 0 as a code for the default start points of both new partitions and of a sector size specified by a plus sign (+ and unit specifier — G for GiB in the case of both of these partitions.
If you want to add names to the partitions to help identify them, you can use the -c option:
# sgdisk -c 1:"Linux data" -c 2:"Shared FAT" -c 3:FreeBSD /dev/sdf The operation has completed successfully. # sudo sgdisk -p /dev/sdf Disk /dev/sdf: 30720000 sectors, 14.6 GiB Model: STORE N GO Sector size (logical/physical): 512/512 bytes Disk identifier (GUID): 739CB37E-1201-47C2-9304-036EE67223F0 Partition table holds up to 128 entries Main partition table begins at sector 2 and ends at sector 33 First usable sector is 34, last usable sector is 30719966 Partitions will be aligned on 2048-sector boundaries Total free space is 1359805 sectors (664.0 MiB) Number Start (sector) End (sector) Size Code Name 1 2048 4196351 2.0 GiB 8300 Linux data 2 4196352 14682111 5.0 GiB 0700 Shared FAT 3 14682112 29362175 7.0 GiB A503 FreeBSD
This example illustrates the fact that quotes are required around partition names if they contain spaces, but quotes need not be used for single-word partition names.
You can use sgdisk to create a script to help automate tasks such as whole-disk cloning or the preparation of disks for OS installation, even if you don't know the target disk's size when writing the script. For instance, suppose you want to install Linux on several computers, each of which will have a BIOS Boot Partition (type code ef02) of 1 MiB, an EFI System partition (ef00) of 550 MiB, a Linux /boot partition (8300) of 1 GiB, and the remainder of the disk space devoted to a Linux LVM (8e00). The following script will accomplish this task:
#!/bin/bash sgdisk -og "$1" sgdisk -n 1:2048:4095 -c 1:"BIOS Boot Partition" -t 1:ef02 "$1" sgdisk -n 2:4096:+550M -c 2:"EFI System Partition" -t 2:ef00 "$1" sgdisk -n 3:0:+1G -c 3:"Linux /boot" -t 3:8300 "$1" ENDSECTOR=$(sgdisk -E "$1") sgdisk -n 4:0:"$ENDSECTOR" -c 4:"Linux LVM" -t 4:8e00 "$1" sgdisk -p "$1"
This script is, of course, fairly simple. Despite this, it illustrates one important feature: By assigning the output of sgdisk -E (containing the number of the last sector in the largest free block) to a variable and then using that value later, the script adapts to disks of different sizes. (A better solution in this case is to use a sector value of 0, which refers to the default value, which is the end of the free space when creating a partition; but I wanted to illustrate this assignment method.) A more sophisticated script could use the output of sgdisk -F, as well, and perform arithmetic—say, splitting the available free space in some ratio between two or more new partitions. The output of the -p, -i, or other options could also be used, although more processing would be required to do so. This approach could be used in a disk-cloning script; partitions on the source disk could be re-created on the target disk, perhaps adapting one or more partitions' sizes as required.
Some caveats are in order. The most important is that error conditions and even varying disk contents can cause unpredictable behavior. For instance, the output of sgdisk varies depending on whether the disk contains an MBR, a GPT, or some other type of partition table. A command such as the assignment to the ENDSECTOR variable in the preceding script could fail if sgdisk encounters a type of disk you don't anticipate. Such a problem is only likely to affect the preceding script if the partition table is badly corrupt; however, if the assignment to ENDSECTOR had been the first line of the script, the script would fail on MBR disks. You should be sure to test your script thoroughly to prevent such problems.
Another issue is that each call to sgdisk takes a certain amount of time. This time increases when the program must write its changes to disk. The preceding script takes about six seconds to execute on a USB flash drive. This time could be reduced by merging the options into fewer calls to sgdisk—perhaps one for clearing the partition table and creating the first three partitions, a second for finding the end sector, and a final one for creating the LVM partition and displaying the final partition table. Making this change reduces the run time to about two seconds on my system. Of course, the USB flash drive I used for testing this effect is slow compared to a hard disk; but if you write a script with many calls to sgdisk and you find it's sluggish, consolidating those calls may make a difference.
Unlike some tools, such as GParted, sgdisk does not create filesystems. Thus, if you want your script to take care of this task, you'll have to use a call to mkfs or a similar utility to do the job. Note, however, that the Linux kernel sometimes continues to use the old partition table after you've made changes. You must remove and re-install a removable disk or reboot the computer before the computer uses the new partition table. Thus, you should be cautious about moving from partition creation to filesystem creation in a script. Such inconsistencies are most likely to occur on disks with mounted partitions, but I've seen them even on disks with no mounted partitions from time to time.
Go on to "Partitioning Advice"
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.