RPI Imager 2.x - Customize local images

README.md

In RPI Imager v2.x the option to customize local images has been removed. In order to have image customization you need to have your own "Content Repository".

Starting with version RPI Imager v2.0.2 the files in this repository can be paths to your local files or URLs to locally hosted files.

local_repo.json illustrates such a minimal configuration for locally hosted files and locally stored files.

If you want to locally host your files, you can do so via python 3 one liner. In the directory where your images are, run:

# Start webserver on port 3333
python3.11 -m http.server 3333

To use this local repo go to "App Options" -> "Content Repository" -> "Use custom file". You will need to re-select this file every time you restart the Imager (due to security concerns).

systemd vs. cloud-init

Newer version of Pi OS use cloudinit-rpi instead of systemd for customization, so your entry has to reflect that OR your custom image does not use cloud-init - aka you remove it during your image adaptation.

I highly recommend you to switch to cloudinit-rpi though, it provides a lot of quality of life improvements, but in a pinch you can still use the systemd format.

local_repo.json

{
    "imager": {
        "latest_version": "2.0.0",
        "url": "https://www.raspberrypi.com/software/",
        "devices": [
            {
                "name": "Raspberry Pi 5",
                "tags": [
                    "pi5-64bit",
                    "pi5-32bit"
                ],
                "default": true,
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_5.png",
                "description": "Raspberry Pi 5, 500 / 500+, and Compute Module 5",
                "matching_type": "exclusive"
            },
            {
                "name": "Raspberry Pi 4",
                "tags": [
                    "pi4-64bit",
                    "pi4-32bit"
                ],
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_4.png",
                "description": "Raspberry Pi 4 Model B, 400, and Compute Module 4 / 4S",
                "matching_type": "inclusive"
            },
            {
                "name": "Raspberry Pi 3",
                "tags": [
                    "pi3-64bit",
                    "pi3-32bit"
                ],
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_3.png",
                "description": "Raspberry Pi 3 Model A+ / B / B+ and Compute Module 3 / 3+",
                "matching_type": "inclusive"
            },
            {
                "name": "Raspberry Pi 2",
                "tags": [
                    "pi2-32bit"
                ],
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_2.png",
                "description": "Raspberry Pi 2 Model B",
                "matching_type": "inclusive"
            },
            {
                "name": "Raspberry Pi 1",
                "tags": [
                    "pi1-32bit"
                ],
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_1B+.png",
                "description": "Raspberry Pi 1 Model A / A+ / B / B+ and Compute Module 1",
                "matching_type": "inclusive"
            },
            {
                "name": "Raspberry Pi Zero 2 W",
                "tags": [
                    "pi3-64bit",
                    "pi3-32bit"
                ],
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_Zero_2_W.png",
                "description": "Raspberry Pi Zero 2 W",
                "matching_type": "inclusive"
            },
            {
                "name": "Raspberry Pi Zero",
                "tags": [
                    "pi1-32bit"
                ],
                "icon": "https://downloads.raspberrypi.com/imager/icons/RPi_Zero.png",
                "description": "Raspberry Pi Zero, Zero W, and Zero WH",
                "matching_type": "inclusive"
            },
            {
                "name": "No filtering",
                "tags": [],
                "description": "Show every possible image",
                "matching_type": "inclusive"
            }
        ]
    },
    "os_list": [
        {
            "name": "Your Image Name (Hosted)",
            "description": "Locally hosted file, works with version >= 2.0.0",
            "icon": "https://downloads.raspberrypi.com/raspios_armhf/Raspberry_Pi_OS_(32-bit).png",
            "url": "http://0.0.0.0:3333/custom_image.img.xz",
            "init_format": "systemd",
            "devices": [
                "pi3-64bit"
            ]
        },
        {
            "name": "Your Image Name (Filepath, systemd)",
            "description": "Locally saved file, works with version >= 2.0.2",
            "icon": "https://downloads.raspberrypi.com/raspios_armhf/Raspberry_Pi_OS_(32-bit).png",
            "url": "file://local/path/to/your/custom_image.img.xz",
            "init_format": "systemd",
            "devices": [
                "pi3-64bit"
            ]
        },
        {
            "name": "Your Image Name (Filepath, cloudinit-rpi)",
            "description": "Locally saved file, works with version >= 2.0.2",
            "icon": "https://downloads.raspberrypi.com/raspios_armhf/Raspberry_Pi_OS_(32-bit).png",
            "url": "file://local/path/to/your/another_custom_image.img.xz",
            "init_format": "cloudinit-rpi",
            "capabilities": [
                "rpi_connect"
            ],
            "devices": [
                "pi3-64bit"
            ]
        }
    ]
}

Note that the 'systemd' init_format will not customise a modern Raspberry Pi OS.

You would instead want to use 'cloudinit-rpi', which would also allow you to use the capabilities flags.

@tdewey-rpi Interesting - I have a custom image based on "Pi OS Lite Trixie (2025-10-01)" and with that, customization works fine. I have not tried with the latest December release though - do you by any chance know the cutoff date at which cloudinit-rpi is mandatory?

Edit: https://www.raspberrypi.com/news/cloud-init-on-raspberry-pi-os/ It seems that this happened some time in November...

Essentially, any Raspberry Pi OS released on or after Imager 2.0's release day (Nov 24, 2025).

Note also that some other operating systems use cloud-init (eg, Ubuntu Server). Additionally, I'm expecting more 3P operating systems to enable cloud-init-rpi support for their Raspberry Pi OSes as time goes by - because this should allow them to expose OS customisation to operating systems that never previously supported it (eg, Fedora based distros like Ultramarine)

Gotcha, thank you @tdewey-rpi !

I will update this as I go.

Looking into cloud-init it might even make my life significantly easier.
If I just knew that two months ago when migrating to Trixie - that's what I get for early adopting Trixie...