How to unpack the img file of the Android firmware

Developing custom firmware, modifying system files or in-depth diagnostics of Android device problems often require access to the internal contents of disk images. Users faced with the need to change the boot logo, remove pre-installed software or add drivers are wondering how to extract the Android firmware img file correctly. This process is not trivial, since images are often compressed with various algorithms or have a specific file system other than the standard FAT or NTFS.

To successfully complete the task, you will need not only an understanding of the Android ROM structure, but also a specialized set of tools that most often work in a Linux environment or through command line emulation. In this article, we will analyze in detail the methods of working with popular image formats, such as system.img, boot.img and recovery.img. You will learn to determine the type of compression, convert formats, and securely extract data for subsequent modification.

It is important to understand that working with firmware images is an intervention in low-level software. An error during repacking or modification may cause the device to stop booting. Therefore, before starting any manipulations, it is recommended to create a complete backup copy of the original files. We will consider both automated scripts and manual methods through the terminal so that you can choose the most suitable option for your operating system.

Preparing the working environment and necessary utilities

Before you start unpacking, you need to prepare the correct software environment. Although there are graphical shells for Windows, the most reliable and flexible tool remains the command line in the Linux or WSL (Windows Subsystem for Linux) environment. This is due to the fact that most tools for working with Android images were originally developed for Unix-like systems.

You will need to install the package Python 3, since many modern scripts for analyzing file headers are written in this language. It is also critically important to have the utility simg2img, which is included in the package android-tools-fsutils. It is necessary to convert Sparse images, often used in system partitions, into regular raw images that can be mounted.

⚠️ Attention: Installing third-party scripts from unverified sources can lead to infection of the system with malware. Use only open source GitHub repositories or official Linux distribution packages.

• 🐧 Operating system: Ubuntu 20.04/22.04 or Debian or WSL2 on Windows is recommended.
• 🐍 Interpreter: Python 3.8 or higher with libraries installed requests and cryptography.
• 🛠 Utilities: android-tools-fsutils, lz4, xz-utils, gzip, simg2img.
• 💾 Disk space: Minimum 10 GB of free space for temporary unpacking files.

To install a basic set of tools on Debian-like systems, it is enough to execute one command in the terminal. This will ensure that all the necessary dependencies are available to work with different types of compression and file systems.

sudo apt-get install android-tools-fsutils python3 python3-pip lz4 xz-utils gzip

Analyzing the file structure and determining the image type

Not all files with the extension .img are the same. There are several formats found in the Android ecosystem, and the decompression method directly depends on the type of image. The first step is always to analyze the file header. The command file allows you to quickly determine what exactly you are dealing with: is it a raw image, a sparse image, a compressed archive, or a specific bootloader format.

The most common types of images include sparse images used for partition system in modern firmware to save space. They contain only occupied data blocks. There are also raw images that represent a complete copy of the partition bit by bit. Separately, it is worth highlighting boot.img and recovery.img, which have their own header structure, different from ext4 or f2fs file systems.

If the command file prints a message saying that this is an "Android sparse image", you will not be able to simply mount it. Pre-conversion required. In case the file is defined as "gzip compressed data" or "xz compressed data", it must first be unpacked with standard archivers before further processing. Incorrect identification of the file type is the most common cause of failures at the initial stage.

File type	Extension	Description	Required tool
Sparse Image	.img	Image with empty blocks (System, Vendor)	simg2img
Raw Image	.img	Full bitmap image of the partition	mount / losetup
Boot/Recovery	.img	Kernel and Ramdisk	unpackbootimg / magiskboot
Compressed	.img.xz, .gz	Compressed image of any type	xz / gzip

Converting Sparse images to Raw format

Modern Android firmware, especially for devices with large capacity memory, use the Sparse format for partitions system, vendor and sometimes product. This format can significantly reduce file size when transmitted over OTA or stored on a server, since it ignores blocks filled with zeros. However, to edit the content, such an image must be converted to the Raw.

format. The conversion process is performed using the utility simg2img. The command is easy to execute, but requires careful attention to file names. The output will be a larger file that will take up space equal to the full size of the device partition, even if the actual data only takes up part of it.

simg2img system_sparse.img system_raw.img

After executing the command, be sure to check the size of the resulting file. If the size system_raw.img is several gigabytes (for example, 4-8 GB), and the original file weighed 500 MB, then the conversion was successful. If the sizes are the same, it is possible that the source file was already in Raw format or there was an error reading the header.

⚠️ Warning: Converting Sparse to Raw requires free disk space greater than the size of the final image. Make sure there is enough space on your partition, otherwise the process will be interrupted midway and the file will be damaged.

Mounting the image and extracting files

After you have received the Raw image (or downloaded it immediately in this format), the next step is to mount it into the Linux file system. This will allow you to work with files inside the image as with a regular folder: copy, delete, edit configuration files or replace applications.

Most Android system partitions use the file system ext4. However, in new devices it is increasingly found f2fs (Flash-Friendly File System), which is optimized for flash memory. Before mounting, it is advisable to know the type of file system, although the Linux kernel often detects it automatically. To mount, you will need to create a mount point - an empty directory.

sudo mkdir /mnt/android_system
sudo mount -o loop system_raw.img /mnt/android_system

If the mount command gives an error about the wrong file system type, try explicitly specifying the type using the key -t. For example, sudo mount -t ext4 -o loop ... or sudo mount -t f2fs -o loop .... After successful mounting, you will have access to all firmware files through a file manager or terminal.

• 📂 Mount point: Create separate folders for each image (system, vendor, data) to avoid confusion.
• 🔒 Access rights: Use sudo to mount, since images contain system files with special rights.
• 💾 Synchronization: After making changes, always run the command sync before unmounting.

Unpacking Boot and Recovery boot images

Images boot.img i recovery.img have a fundamentally different structure compared to system partitions. They do not contain a full-fledged ext4 file system, but are a combination of the kernel (kernel), the second stage of the bootloader (second stage bootloader) and the disk RAM image (ramdisk). Simple mounting will not work here.

To work with these files, use a specialized tool unpackbootimg or a more modern one magiskboot (included with Magisk). These utilities parse the image header and extract the components into separate files. Ramdisk, in turn, is often compressed by algorithms gzip, lz4 or xz, and must be unpacked separately.

Structure of Boot.img

The image consists of a header (512 bytes), a kernel, a second bootloader (optional), ramdisk and DTB (Device Tree Blob). Changing the DTB without matching the hardware will result in a “brick” of the device.

Unpacking process via unpackbootimg looks like this: the utility creates a folder with the name of the image, where it places the extracted kernel (often with the extension .gz) and the file ramdisk.cpio. Next, the ramdisk needs to be unpacked with the command cpio. This is a critical step for those who are creating custom recoveries or patching the kernel.

./unpackbootimg -i boot.img
cd boot.img-out
gunzip -c kernel.gz > kernel
mkdir ramdisk
cd ramdisk
cpio -i -F ../ramdisk.cpio

⚠️ Attention: When modifying the ramdisk, be careful with file permissions (chmod/chown). Incorrect rights to executable files in init scripts can prevent Android from loading.

Repacking and creating a new image

After making all the necessary changes to the firmware files, you need to correctly assemble the image back. Simply copying the files back to the mounted drive is not enough - you need to preserve the metadata, permissions, and symbolic links. To do this, use the utility mke2fs or scripts from the set make_ext4fs.

If you have worked with ext4, the best way is to create a new clean image of the required size and copy the changed files there while preserving the attributes. The cp -a (archive mode) command is necessary to save all links and rights. After this, the image can be converted again to sparse format using img2simg to reduce the size before flashing.

For boot images (boot.img), the utility mkbootimgis used. It requires specifying the paths to the kernel, ramdisk, cmdline and boot addresses (base address), which were obtained during unpacking. Losing these parameters will make the image inoperative, so carefully save the output of the unpacking utility.

mkbootimg --kernel kernel --ramdisk ramdisk.cpio --cmdline "..." --base 0x... -o new_boot.img

Frequently asked questions (FAQ)

Can I unpack an img file on Windows without installing Linux?

It is technically possible to use ported versions of the utilities (for example, through Cygwin or ready-made tool builds on GitHub), but this often leads to errors due to differences in handling access rights and file paths. The most stable result is achieved when using WSL2 (Windows Subsystem for Linux), which provides a full-fledged Linux kernel inside Windows.

What should you do if you get a "wrong fs type" error when mounting?

Most likely, you are trying to mount the Sparse image as Raw. Make sure to convert via simg2img. If the image is already Raw, try explicitly specifying the file system type (-t ext4 or -t f2fs). Also check if the firmware file itself is damaged when downloading.

How to find out what compression algorithm is used in the ramdisk?

Use the command file ramdisk.cpio or look at the first bytes of the file in a hexadecimal editor. Magic numbers at the beginning of the file will indicate the compression type: 1F 8B for gzip, 02 21 4C 18 for lz4. Incorrect definition will result in an unpacking error.

Is it safe to edit system applications inside system.img?

Editing system applications (for example, removing bloatware) is safe as long as you understand the dependencies between packages. Removing critical system components may result in a cyclic reboot (bootloop). Always have a working recovery image (TWRP) on hand to roll back changes.