GPT Image

Create GUID Partition Table disk images on local disks. Written in pure Python gpt-image allows GPT disk images to be built on a local filesystem and exported to a destination device.

This is useful for creating a disk image on SD Cards or embedded devices.

Quick Start

Installation

pip install gpt-image

Create a GPT disk image

from gpt_image.disk import Disk
from gpt_image.partition import Partition, PartitionType

# create a new, 16 MB disk, size is in bytes
disk = Disk("disk-image.raw")
disk.create(16 * 1024 * 1024)

# create a 2MB Linux partition named "boot"
boot_part = Partition(
        "boot", 
        2 * 1024 * 1024, 
        PartitionType.EFI_SYSTEM_PARTITION.value
    )
disk.table.partitions.add(boot_part)

# create an 8MB Linux partition named "data"
data_part = Partition(
        "data", 
        8 * 1024 * 1024, 
        PartitionType.LINUX_FILE_SYSTEM.value
    )
disk.table.partitions.add(data_part)

# commit the change to disk
disk.commit()

# dump the current GPT information:

print(disk)

The final print(disk) command outputs a JSON document of the current GPT configuration:

{
  "path": "disk-image.raw",
  "image_size": 16777216,
  "sector_size": 512,
  "primary_header": {
    "backup": false,
    "signature": "EFI PART",
    "revision": "\u0000\u0000\u0001\u0000",
    "header_size": 92,
    "header_crc32": 3533962731,
    "reserved": 0,
    "my_lba": 1,
    "alternate_lba": 32767,
    "first_usable_lba": 34,
    "last_usable_lba": 32734,
    "disk_guid": "3f09c9fe-66ea-4c67-b0fb-fd35906b393a",
    "partition_entry_lba": 2,
    "number_of_partition_entries": 128,
    "size_of_partition_entries": 128,
    "partition_entry_array_crc32": 673632436
  },
  "backup_header": {
    "backup": true,
    "signature": "EFI PART",
    "revision": "\u0000\u0000\u0001\u0000",
    "header_size": 92,
    "header_crc32": 727034965,
    "reserved": 0,
    "my_lba": 32767,
    "alternate_lba": 1,
    "first_usable_lba": 34,
    "last_usable_lba": 32734,
    "disk_guid": "3f09c9fe-66ea-4c67-b0fb-fd35906b393a",
    "partition_entry_lba": 32735,
    "number_of_partition_entries": 128,
    "size_of_partition_entries": 128,
    "partition_entry_array_crc32": 673632436
  },
  "partitions": [
    {
      "type_guid": "C12A7328-F81F-11D2-BA4B-00A0C93EC93B",
      "partition_name": "boot",
      "partition_guid": "67ed0675-9d44-46a6-bc29-99a2778e7563",
      "first_lba": 40,
      "last_lba": 4135,
      "alignment": 8,
      "size": 2097152,
      "attribute_flags": []
    },
    {
      "type_guid": "0FC63DAF-8483-4772-8E79-3D69D8477DE4",
      "partition_name": "data",
      "partition_guid": "1a44bc84-bb53-4f9f-b699-1d1268bfdbfa",
      "first_lba": 4136,
      "last_lba": 20519,
      "alignment": 8,
      "size": 8388608,
      "attribute_flags": []
    }
  ]
}

CHANGELOG

v0.8.0 (2023-09-07)

Feature

• feat: read partition data (1bd9159)

• feat: write data function (7b8c176)

• feat: add partition find function (7d810cf)

v0.7.0 (2022-09-11)

Documentation

• docs: update partition type to use enum (bf5ddbc)

Feature

• feat: change disk open API

Allows the disk.open() function to be called without first creating a disk.Disk instance. (5259629)

v0.6.8 (2022-09-10)

Fix

• fix: add partition GUID for Linux, Windows, Mac

Add additional partition UUID values for common OS's (e45c102)

v0.6.7 (2022-08-09)

Chore

• chore: reformat readme (c4533a9)

Fix

• fix: raise an error if partition is too large (f4b1fca)

Unknown

• simplify imports in readme (801ff40)

v0.6.6 (2022-08-02)

Ci

• ci: add gdisk verification tests (091b1e0)

Documentation

• docs: update quick start example (d28dd28)

Fix

• fix: ensure disk GUID's match in header

primary and backup header must match. This ensure the backup uses the primary's GUID and adds a test to check.

fixes #39 (5b7503f)

Refactor

• refactor: change disk.write() function name (94dd23e)

• refactor: remove partition write function (be423c7)

v0.6.5 (2022-07-31)

Chore

• chore: add mypy strict type hints for partition module (90d17f9)

• chore: add mypy strict type hints for disk module (93ddf50)

• chore: update doc comments for partition module (566ef26)

• chore: cleanup disk module formatting and docs (6e7eebe)

• chore: change read method to unmarshal

change to more descriptive name. read() may be used in the class for something else in the future (27e13a3)

Fix

• fix: add types tests to CI

Closes #15 (fee4da6)

v0.6.4 (2022-07-28)

Documentation

• docs: denote partition UUID in creation step (8f768d7)

Fix

• fix: make attributes integer-like

Replace the PartitionAttribute Enum base class with IntEnum to allow integer comparison (1f875cb)

v0.6.3 (2022-07-27)

Fix

• fix: add py.typed to package (3b13b41)

v0.6.2 (2022-07-25)

Fix

• fix: add disk image data to string repr (2d5b3ef)

v0.6.1 (2022-07-24)

Chore

• chore: restore main repo for release workflow (df5491f)

Fix

• fix: Return friendly partition attribute flags

Return the bit position(s) of the partition attribute flag if set. (6fb826f)

v0.6.0 (2022-07-23)

Feature

• feat: add JSON output of objects

Closes #22 (467f104)

v0.5.0 (2022-07-14)

Feature

• feat: migrate to struct module

Removes the Entry class in favor of the builtin struct module. This will simplify marshalling the disk image byte data. (aaa777f)

v0.4.2 (2022-07-12)

Chore

• chore: update Readme with uuid import (614b123)

Fix

• fix: allow setting the partition attribute on init (523e220)

• fix: import modules in package namespace (c35476f)

Unknown

• fix formatting (f5b8210)

v0.4.1 (2022-07-09)

Fix

• fix: use EFI spec mnemonics for attribute names (0e62e24)

v0.4.0 (2022-05-28)

Feature

• feat: allow setting partition attributes (fa73bde)

v0.3.2 (2022-05-21)

Ci

• ci: add integration test using sfdisk

Add an integration test using sfdisk to test the resulting GPT image (af0b26a)

Fix

• fix: custom partition error class (bf2cdaa)

• fix: add missing types (f348697)

v0.3.1 (2022-05-08)

Fix

• fix: allow guid to be None or UUID type (c2f15c7)

• fix: add marshal function

Use object property to marshal bytes (a7e06fd)

Unknown

• ignore *.raw files in test directory (fba4b56)

v0.3.0 (2022-05-07)

Feature

• feat: read existing disk (#14)

• feat: read existing disk

Opens an existing disk image and ummarshals it to a gpt_image object (ed83cb0)

v0.2.2 (2022-04-03)

Fix

• fix: adjust pmbr partition size (#13)

Fix the protective MBR partition size value (379d615)

Unknown

• add long description to release

[release skip] (2b73f31)

v0.2.1 (2022-02-27)

Fix

• fix: add partition tests (#9) (da41ad2)

v0.2.0 (2022-02-26)

Ci

• ci: build with build instead of poetry (#6) (d4972cb)

Documentation

• docs: update comments (73e7052)

Feature

• feat: add semantic release (#10) (95177b2)

Fix

• fix: set version (a4262c1)

• fix: use setup.py for package version (3d69f94)

• fix: remove partition wrapper

Use the partition object directly when creating partitions (1f491ad)

• fix: move logic to Disk object

Moves functionality to the disk object to simplify the creation of partitions (4ab2211)

Test

• test: add table module tests (a133a92)

Unknown

• 4 write data (#7)

Allow writing byte data individual partitions (c0680cd)

• test with 3.8 (3fd92d7)

• Create python-app.yml (de8fa64)

• Rename Partition Entry (2ec80ec)

• Convert data (#2)

• Convert Entry data to bytes

• Remove MBR magic numbers (3ecdbe7)

• Merge pull request #1 from swysocki/feature/partition-module

Move partitions to Python Class (b4d97dc)

• Use Entry class (a05226e)

• Separate partition module (d0be1fb)

• wip: separate partition module (6f6a00b)

• wip: remove comments (f2ac4a3)

• Add disk module tests (3952f81)

• wip: correct partition CRC

The partition name wasn't being padded to 72 bytes. Now the alignments need fixing. (6809e4e)

• wip: adding partition

adding a partition works but the CRC for the tables are invalid. (73a6973)

• wip: create default partition array entry (df52857)

• Bare GPT working

Protective MBR and GPT functioning. Partition CRC's are not calculated correctly when a partition is created. (4a8dc0f)

• wip: add protective MBR (8f797c0)

• wip: test writing a single partition (d06e785)

• wip: create new partition (f6b1ccf)

• wip: initial raw disk (e31a479)

• wip: write headers (05aab61)

• wip: more surgery (c2ea588)

• change package name (6cf051e)

• wip: write geometry tests (28602f4)

• wip: clumsy version of seperating headers (0105626)

• reorder checksum functions (9175c7d)

• Zero enter disk in tests

use the disk.create() function to seek to the end of the buffer effectively zeroing the buffer so checksums will work before writing to disk (48e827d)

• Set partition array size to 128 (ed111ad)

• fix test (e308574)

• wip: header crc (e297700)

• all header section tests (5d05fe2)

• test both headers (58cef2a)

• Initial commit (1a2d21a)

• wip: remaining header fields (480ba3f)

• wip: disk GUID (2644991)

• wip: refactor header creation (96a3036)

• wip: header lba (d204cd9)

• fix offset for first header

avoid truncating image file by writing last byte (40e636c)

• wip: first table header section (0f8d9ef)

• Initial commit (fc1523c)

MIT License

Copyright (c) 2021 Scott Wysocki

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.