Android Image Tool

https://github.com/zmj64351508/imgtool
Admin
Android Image Tool is a utility for packing and unpacking Android device images including ramdisk,...
Tokens:4,119
Snippets:32
Trust Score:5.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Manual Kernel Replacement Workflow

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Manual steps for replacing a kernel in a boot image, including unpacking, copying the new kernel, modifying ramdisk, repacking, and cleaning up.

```bash
# 1. Unpack the boot image
./imgtool.py ramdisk unpack boot.img working_dir
```

```bash
# 2. Replace the kernel
cp /path/to/new/zImage working_dir/zImage
```

```bash
# 3. Optionally modify ramdisk contents
# Edit files in working_dir/ramdisk/
```

```bash
# 4. Repack the boot image
./imgtool.py ramdisk pack working_dir new_boot.img
```

```bash
# 5. Clean up
./imgtool.py ramdisk clean working_dir
```

--------------------------------

### Pack Android Boot Image (Ramdisk)

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Rebuilds a boot image from a directory containing the kernel and ramdisk. Custom boot parameters like command line, base address, page size, and ramdisk offset can be specified. The shortcut script `./pack.ramdisk` is also available.

```bash
# Basic usage - pack from directory to default output (new_ramdisk.img)
./imgtool.py ramdisk pack ramdisk_unpacked
```

```bash
# Pack with custom output filename
./imgtool.py ramdisk pack ramdisk_unpacked custom_boot.img
```

```bash
# Pack with custom boot parameters
./imgtool.py ramdisk pack ramdisk_unpacked new_boot.img \
    --cmdline "console=ttyS1,115200n8 rootdelay=2 selinux=0" \
    --base 0x02008000 \
    --page_size 4096 \
    --ramdisk_offset 0x02000000
```

```bash
# Using the shortcut wrapper script
./pack.ramdisk ramdisk_unpacked
```

--------------------------------

### Replace Kernel in Boot Image

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Automates the process of replacing the kernel in a boot image. Supports default parameters or custom page size and kernel path.

```bash
# Using the standalone replace_kernel.sh script
# Default: page_size=4096, kernel from ~/Work/repository/elite-project
./replace_kernel.sh boot.img
```

```bash
# Using the utils version with custom parameters
# Syntax: ./utils/replace_kernel.sh [page_size] [kernel_path]
./utils/replace_kernel.sh 8192
```

```bash
./utils/replace_kernel.sh 8192 ~/work/my-kernel-project
```

--------------------------------

### Ext4 Pack API

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Creates a new sparse ext4 image from a directory containing filesystem contents.

```APIDOC
## Ext4 Pack

### Description
Creates a new sparse ext4 image from a directory containing the filesystem contents. Supports SELinux file contexts and configurable image size.

### Method
`./imgtool.py ext4 pack`

### Endpoint
`/ext4/pack`

### Parameters
#### Path Parameters
- **ext_unpacked** (directory) - Required - The input directory containing the unpacked image files (including the `fs/` subdirectory).
- **/system** (string) - Required - The Android mount point for the filesystem (e.g., `/system`, `/data`).
- **new_system.img** (file) - Required - The output filename for the new sparse ext4 image.

#### Query Parameters
- **--size** (string) - Optional - The desired size of the output image (e.g., `512M`, `1G`). Defaults to `512M`.
- **--file_contexts** (file) - Optional - A file containing SELinux file contexts for labeling.

### Request Example
```bash
# Basic usage - pack directory into ext4 image
./imgtool.py ext4 pack ext_unpacked /system new_system.img \
    --size 512M \
    --file_contexts file_contexts

# Using the shortcut wrapper script
./pack.ext4 ext_unpacked /system new_system.img --size 1G --file_contexts file_contexts
```

### Response
#### Success Response (200)
- **new_system.img** (file) - The newly created sparse ext4 image.
```

--------------------------------

### Unpack Android Boot Image (Ramdisk)

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Extracts a boot.img into its kernel (zImage) and ramdisk filesystem components. Specify a custom output directory if needed. The shortcut script `./unpack.ramdisk` can also be used.

```bash
# Basic usage - unpack boot.img to default output directory (ramdisk_unpacked)
./imgtool.py ramdisk unpack boot.img
```

```bash
# Unpack to a custom output directory
./imgtool.py ramdisk unpack boot.img my_output_dir
```

```bash
# Using the shortcut wrapper script
./unpack.ramdisk boot.img
```

--------------------------------

### Pack Android Ext4 Image

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Creates a sparse ext4 image from a directory containing filesystem contents. Supports SELinux file contexts and configurable image size. The shortcut script `./pack.ext4` can also be used.

```bash
# Basic usage - pack directory into ext4 image
./imgtool.py ext4 pack ext_unpacked /system new_system.img \
    --size 512M \
    --file_contexts file_contexts
```

```bash
# Using the shortcut wrapper script
./pack.ext4 ext_unpacked /system new_system.img --size 1G --file_contexts file_contexts
```

--------------------------------

### Ramdisk Pack API

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Rebuilds an Android boot image from a directory containing the kernel and ramdisk filesystem.

```APIDOC
## Ramdisk Pack

### Description
Rebuilds an Android boot image from a previously unpacked directory containing the kernel (zImage) and ramdisk filesystem. Supports customization of boot parameters including kernel command line, base address, page size, and ramdisk offset.

### Method
`./imgtool.py ramdisk pack`

### Endpoint
`/ramdisk/pack`

### Parameters
#### Path Parameters
- **ramdisk_unpacked** (directory) - Required - The directory containing the unpacked ramdisk files (zImage and ramdisk/ directory).
- **custom_boot.img** (file) - Optional - The filename for the new boot image.

#### Query Parameters
- **--cmdline** (string) - Optional - Kernel command line arguments.
- **--base** (hex) - Optional - Base address for the boot image.
- **--page_size** (integer) - Optional - Page size of the boot image.
- **--ramdisk_offset** (hex) - Optional - Offset of the ramdisk within the boot image.

### Request Example
```bash
# Basic usage - pack from directory to default output (new_ramdisk.img)
./imgtool.py ramdisk pack ramdisk_unpacked

# Pack with custom output filename
./imgtool.py ramdisk pack ramdisk_unpacked custom_boot.img

# Pack with custom boot parameters
./imgtool.py ramdisk pack ramdisk_unpacked new_boot.img \
    --cmdline "console=ttyS1,115200n8 rootdelay=2 selinux=0" \
    --base 0x02008000 \
    --page_size 4096 \
    --ramdisk_offset 0x02000000

# Using the shortcut wrapper script
./pack.ramdisk ramdisk_unpacked
```

### Response
#### Success Response (200)
- **new_boot.img** (file) - The newly created boot image.

### Default Parameter Values
- **cmdline**: "console=ttyS1,115200n8 rootdelay=2 no_console_suspend selinux=0"
- **base**: 0x02008000
- **page_size**: 4096
- **ramdisk_offset**: 0x02000000
```

--------------------------------

### Unpack Android Ext4 Image

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Extracts a sparse ext4 image (e.g., system.img) to a raw format and mounts its filesystem. Requires root privileges for mounting. A custom output directory can be specified. The shortcut script `./unpack.ext4` is also available.

```bash
# Basic usage - unpack ext4 image to default output (ext_unpacked)
sudo ./imgtool.py ext4 unpack system.img
```

```bash
# Unpack to custom output directory
sudo ./imgtool.py ext4 unpack system.img my_system_dir
```

```bash
# Using the shortcut wrapper script
sudo ./unpack.ext4 system.img
```

--------------------------------

### Split Android Boot Image

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Parses an Android boot image header to extract kernel and ramdisk components. Outputs image structure details and generates component files.

```bash
# Split a boot image into components
./utils/split_bootimg.pl boot.img
```

--------------------------------

### Ext4 Clean API

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Unmounts the loopback filesystem and removes the unpacked ext4 directory.

```APIDOC
## Ext4 Clean

### Description
Unmounts the loopback filesystem if mounted and removes the unpacked ext4 directory. Requires root privileges if the filesystem is currently mounted.

### Method
`sudo ./imgtool.py ext4 clean`

### Endpoint
`/ext4/clean`

### Parameters
#### Path Parameters
- **my_system_dir** (directory) - Optional - The specific output directory to clean. If not provided, the default directory (`ext_unpacked`) is cleaned.

### Request Example
```bash
# Clean default output directory (ext_unpacked)
sudo ./imgtool.py ext4 clean

# Clean a specific output directory
sudo ./imgtool.py ext4 clean my_system_dir
```

### Response
#### Success Response (200)
- Indicates successful unmounting and removal of the specified directory.
```

--------------------------------

### Ramdisk Unpack API

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Extracts an Android boot image (boot.img) into its kernel (zImage) and ramdisk filesystem components.

```APIDOC
## Ramdisk Unpack

### Description
Extracts an Android boot image (boot.img) into its component parts: kernel (zImage) and ramdisk filesystem. The tool parses the boot image header to determine offsets and sizes, then extracts the kernel and decompresses the gzipped ramdisk cpio archive into a directory structure that can be modified.

### Method
`./imgtool.py ramdisk unpack`

### Endpoint
`/ramdisk/unpack`

### Parameters
#### Path Parameters
- **boot.img** (file) - Required - The input boot image file.
- **my_output_dir** (directory) - Optional - The custom output directory for unpacked files.

### Request Example
```bash
# Basic usage - unpack boot.img to default output directory (ramdisk_unpacked)
./imgtool.py ramdisk unpack boot.img

# Unpack to a custom output directory
./imgtool.py ramdisk unpack boot.img my_output_dir

# Using the shortcut wrapper script
./unpack.ramdisk boot.img
```

### Response
#### Success Response (200)
- **zImage** (file) - The extracted kernel image.
- **ramdisk/** (directory) - The extracted ramdisk filesystem.

#### Response Example
```
# Expected output structure:
# ramdisk_unpacked/
# &nbsp;&nbsp;&nbsp;&nbsp;├── zImage              # Extracted kernel
# &nbsp;&nbsp;&nbsp;&nbsp;└── ramdisk/            # Extracted ramdisk filesystem
#     &nbsp;&nbsp;&nbsp;&nbsp;├── init.rc
#     &nbsp;&nbsp;&nbsp;&nbsp;├── init
#     &nbsp;&nbsp;&nbsp;&nbsp;├── default.prop
#     &nbsp;&nbsp;&nbsp;&nbsp;└── ...
```
```

--------------------------------

### Clean Ext4 Unpack Directory

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Unmounts the loopback filesystem if mounted and removes the unpacked ext4 directory. Requires root privileges if the filesystem is currently mounted. This can be used for the default or a specified directory.

```bash
# Clean default output directory (ext_unpacked)
sudo ./imgtool.py ext4 clean
```

```bash
# Clean a specific output directory
sudo ./imgtool.py ext4 clean my_system_dir
```

--------------------------------

### Ext4 Unpack API

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Extracts an Android sparse ext4 image by converting it to raw format and mounting it.

```APIDOC
## Ext4 Unpack

### Description
Extracts an Android sparse ext4 image (system.img, userdata.img, etc.) by converting it to raw format and mounting it as a loopback device. Requires root privileges for the mount operation.

### Method
`sudo ./imgtool.py ext4 unpack`

### Endpoint
`/ext4/unpack`

### Parameters
#### Path Parameters
- **system.img** (file) - Required - The input sparse ext4 image file.
- **my_system_dir** (directory) - Optional - The custom output directory for unpacked files.

### Request Example
```bash
# Basic usage - unpack ext4 image to default output (ext_unpacked)
sudo ./imgtool.py ext4 unpack system.img

# Unpack to custom output directory
sudo ./imgtool.py ext4 unpack system.img my_system_dir

# Using the shortcut wrapper script
sudo ./unpack.ext4 system.img
```

### Response
#### Success Response (200)
- **ext_unpacked/** (directory) - The directory containing the unpacked filesystem.
  - **system.img-raw** (file) - The raw (non-sparse) image file.
  - **fs/** (directory) - The mounted filesystem (requires root).

#### Response Example
```
# Expected output structure:
# ext_unpacked/
# &nbsp;&nbsp;&nbsp;&nbsp;├── system.img-raw      # Raw (non-sparse) image
# &nbsp;&nbsp;&nbsp;&nbsp;└── fs/                 # Mounted filesystem (requires root)
#     &nbsp;&nbsp;&nbsp;&nbsp;├── app/
#     &nbsp;&nbsp;&nbsp;&nbsp;├── bin/
#     &nbsp;&nbsp;&nbsp;&nbsp;├── etc/
#     &nbsp;&nbsp;&nbsp;&nbsp;├── lib/
#     &nbsp;&nbsp;&nbsp;&nbsp;└── ...
```
```

--------------------------------

### Unpack YAFFS2 Filesystem Image

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Extracts a YAFFS2 filesystem image. Supports custom page sizes and output directories. Default page size is 4096.

```bash
# Basic usage - unpack yaffs2 image to default output (yaffs_unpacked)
./imgtool.py yaffs2 unpack system.yaffs2
```

```bash
# Unpack with custom page size
./imgtool.py yaffs2 unpack system.yaffs2 my_output --page_size 2048
```

```bash
# Using the shortcut wrapper script
./unpack.yaffs2 system.yaffs2
```

--------------------------------

### Ramdisk Clean API

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Removes the unpacked ramdisk directory and all extracted contents.

```APIDOC
## Ramdisk Clean

### Description
Removes the unpacked ramdisk directory and all extracted contents. Useful for cleanup after modifications are complete or to start fresh.

### Method
`./imgtool.py ramdisk clean`

### Endpoint
`/ramdisk/clean`

### Parameters
#### Path Parameters
- **my_output_dir** (directory) - Optional - The specific output directory to clean. If not provided, the default directory (`ramdisk_unpacked`) is cleaned.

### Request Example
```bash
# Clean default output directory (ramdisk_unpacked)
./imgtool.py ramdisk clean

# Clean a specific output directory
./imgtool.py ramdisk clean my_output_dir
```

### Response
#### Success Response (200)
- Indicates successful removal of the specified directory.
```

--------------------------------

### Clean Ramdisk Unpack Directory

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Removes the unpacked ramdisk directory and its contents. Use this to clean up the default output directory or a specified custom directory.

```bash
# Clean default output directory (ramdisk_unpacked)
./imgtool.py ramdisk clean
```

```bash
# Clean a specific output directory
./imgtool.py ramdisk clean my_output_dir
```

--------------------------------

### Clean YAFFS2 Unpacked Directory

Source: https://context7.com/zmj64351508/imgtool/llms.txt

Removes the unpacked YAFFS2 directory and all extracted filesystem contents. Can clean the default or a specified directory.

```bash
# Clean default output directory (yaffs_unpacked)
./imgtool.py yaffs2 clean
```

```bash
# Clean a specific output directory
./imgtool.py yaffs2 clean my_yaffs_output
```
Tokens:
Raw