---
title: DiskImageKit
framework: diskimagekit
role: collection
role_heading: Framework
path: diskimagekit
---

# DiskImageKit

Create, open, and manage disk images.

## Overview

Overview The DiskImageKit framework provides an API for creating, opening, and managing disk images. It’s designed primarily for use with the Virtualization framework, enabling seamless integration of disk images as storage for virtual machines. Supported Formats DiskImageKit supports two disk image formats: ASIF: Apple Sparse Image Format. ASIF images support both standalone and stacked configurations. RAW: Traditional raw disk image format. You can only use RAW images as standalone images or as base images in stacked configurations. Stacked Disk Images A key feature of DiskImageKit is support for stacked disk images, where multiple image layers are combined into a single logical disk. This enables powerful workflows: Base layer: A read-only foundation image (can be shared across multiple VMs, for example). Cache layer: Stores blocks read from the layer beneath it (useful when that layer is on slow storage). Overlay layers: Store modifications to the base image (enables copy-on-write snapshots). Stacked images allow you to: Reduce storage space by sharing a common base image. Implement snapshot and restore functionality. Optimize performance with caching layers. Getting started Create a standalone ASIF image Create a standalone disk image: import DiskImageKit

// Create a 40 GB ASIF disk image with 512-byte blocks.     let imageURL = URL(fileURLWithPath: "/path/to/disk.asif")     let blockCount = 40 * 1000 * 1000 * 1000 / 512

let diskImage = try DiskImage(creating: .asif(         url: imageURL,         blockCount: blockCount,         blockSize: .bytes512     )) Open an existing image Open any existing disk image (standalone or layer):     let diskImage = try DiskImage(opening: .open(url: imageURL))

print("Format: \(diskImage.format)")     print("Size: \(diskImage.blockCount) blocks of \(diskImage.blockSize.rawValue) bytes")

if let layerType = diskImage.layerType {         print("Layer type: \(layerType == .cache ? "Cache" : "Overlay")")     } Create a stacked disk image Build a multi-layer disk image:     // 1. Open an existing base image.     let baseImage = try DiskImage(opening: .open(url: baseImageURL))

// 2. Add a cache layer. This step improves performance when base is on network storage.     var stackedImage = try baseImage.appending(.asifLayer(url: cacheURL, type: .cache))

// 3. Add an overlay layer (stores all writes).     stackedImage = try stackedImage.appending(.asifLayer(url: overlayURL, type: .overlay)) Use disk images with the Virtualization framework Pass the disk image - either a standalone image or a stack - to the Virtualization framework:     import Virtualization     let storageAttachment = try VZDiskImageStorageDeviceAttachment(diskImage: diskImage) Truncate or extend disk images You can truncate or extend disk images (this does not resize the filesystem inside the image):     let diskImage = try DiskImage(opening: .open(url: imageURL))          // Truncate to 80 GB (in 512-byte blocks).     let newBlockCount = 80 * 1000 * 1000 * 1000 / 512     try diskImage.truncate(blockCount: newBlockCount)     note: For stacked images, truncating affects the top layer, which determines the stack’s effective size. Inspect disk images with image properties DiskImage objects provide various properties to inspect disk images: let diskImage = try DiskImage(opening: .open(url: imageURL))

print("Block count: \(diskImage.blockCount).") print("Block size: \(diskImage.blockSize.rawValue) bytes.") print("Format: \(diskImage.format)") print("Open mode: \(diskImage.openMode).")

if let layerType = diskImage.layerType {     switch layerType {     case .cache:         print("This is a cache layer.")     case .overlay:         print("This is an overlay layer.")     } }

// UUID tracking (for stacked images). if let layerUUID = diskImage.layerUUID {     print("Layer UUID: \(layerUUID).") } if let parentUUID = diskImage.parentUUID {     print("Parent UUID: \(parentUUID).") }

Important details about stacked disk images Remember to keep the following details in mind when working with stack disk images: One cache layer per stack: The framework allows only one cache layer per stacked disk image. Layer ordering matters: Layers are processed from bottom (base) to top. The topmost layer determines the stack’s size and receives all writes. UUID compatibility: When appending a new layer using appending(_:), the framework sets the parentUUID of the layer to the layerUUID of its parent layer (unless the parent is a raw image, which has no UUID). The layer UUID changes if the layer is written to, to prevent using stacks with incompatible layers. Appending an existing layer using appending(_:) fails if there is such a mismatch.

## Topics

### Essential Types

- [DiskImage](diskimagekit/diskimage.md)
- [StackedImage](diskimagekit/stackedimage.md)
- [OpenConfigurationProtocol](diskimagekit/openconfigurationprotocol.md)
- [OpenConfiguration](diskimagekit/openconfiguration.md)
- [OpenConfiguration.Mode](diskimagekit/openconfiguration/mode-swift.enum.md)

### Creating disk images

- [init(creating:)](diskimagekit/diskimage/init(creating:).md)
- [ASIFCreationConfiguration](diskimagekit/asifcreationconfiguration.md)
- [ASIFLayerCreationConfiguration](diskimagekit/asiflayercreationconfiguration.md)
- [DiskImage.CreationConfiguration](diskimagekit/diskimage/creationconfiguration.md)
- [RAWCreationConfiguration](diskimagekit/rawcreationconfiguration.md)

### Opening and closing disk images

- [init(opening:)](diskimagekit/diskimage/init(opening:).md)

### Appending layers and resizing existing images

- [DiskImage.StackableLayer](diskimagekit/diskimage/stackablelayer.md)
- [appending(_:)](diskimagekit/diskimage/appending(_:)-4wifj.md)

### Values that describe block sizes and image formats

- [DiskImage.Format](diskimagekit/diskimage/format-swift.enum.md)
- [DiskImage.BlockSize](diskimagekit/diskimage/blocksize-swift.enum.md)
- [DiskImage.LayerType](diskimagekit/diskimage/layertype-swift.struct.md)

### Errors

- [IncompatibleStackingError](diskimagekit/incompatiblestackingerror.md)
- [InvalidBlockCountError](diskimagekit/invalidblockcounterror.md)
- [CorruptedImageError](diskimagekit/corruptedimageerror.md)
- [UnsupportedFormatError](diskimagekit/unsupportedformaterror.md)