#image #kernel #binary #bootimage

bin+lib bootimage

Tool to create a bootable OS image from a kernel binary

49 releases

✓ Uses Rust 2018 edition

new 0.7.3 Apr 21, 2019
0.6.6 Mar 26, 2019
0.5.7 Nov 25, 2018
0.5.5 Jul 26, 2018
0.2.1 Mar 31, 2018
Download history 188/week @ 2019-01-06 324/week @ 2019-01-13 426/week @ 2019-01-20 352/week @ 2019-01-27 621/week @ 2019-02-03 379/week @ 2019-02-10 195/week @ 2019-02-17 428/week @ 2019-02-24 374/week @ 2019-03-03 486/week @ 2019-03-10 251/week @ 2019-03-17 615/week @ 2019-03-24 762/week @ 2019-03-31 502/week @ 2019-04-07 411/week @ 2019-04-14

1,885 downloads per month




Creates a bootable disk image from a Rust OS kernel.


> cargo install bootimage


First you need to add a dependency on the bootloader crate:

# in your Cargo.toml

bootloader = "0.5.1"

Note: At least bootloader version 0.5.1 is required since bootimage 0.7.0. For earlier bootloader versions, use bootimage 0.6.6.

If you want to use a custom bootloader with a different name, you can use Cargo's rename functionality.


Now you can build the kernel project and create a bootable disk image from it by running:

bootimage build --target your_custom_target.json [other_args]

The command will invoke cargo xbuild, forwarding all passed options. Then it will build the specified bootloader together with the kernel to create a bootable disk image.

If you prefer a cargo subcommand, you can use the equivalent cargo bootimage command:

cargo bootimage --target your_custom_target.json [other_args]


To run your kernel in QEMU, you can use bootimage run:

bootimage run --target your_custom_target.json [other_args] -- [qemu args]

All arguments after -- are passed to QEMU. If you want to use a custom run command, see the Configuration section below.

If you prefer working directly with cargo, you can use bootimage runner as a custom runner in your .cargo/config:

[target.'cfg(target_os = "none")']
runner = "bootimage runner"

Now you can run your kernel through cargo xrun --target [].


Configuration is done through a through a [package.metadata.bootimage] table in the Cargo.toml of your kernel. The following options are available:

    # This target is used if no `--target` is passed
    default-target = ""

    # The command invoked with the created bootimage (the "{}" will be replaced
    # with the path to the bootable disk image)
    # Applies to `bootimage run` and `bootimage runner`
    run-command = ["qemu-system-x86_64", "-drive", "format=raw,file={}"]

    # Additional arguments passed to the run command for non-test executables
    # Applies to `bootimage run` and `bootimage runner`
    run-args = []

    # Additional arguments passed to the run command for test executables
    # Applies to `bootimage runner`
    test-args = []

    # An exit code that should be considered as success for test executables
    test-success-exit-code = {integer}

    # The timeout for running a test through `bootimage test` or `bootimage runner` (in seconds)
    test-timeout = 300


Licensed under either of

at your option.

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.


~70K SLoC