🚀 Installation Guide

Follow these steps to replace ChromeOS with CobaltOS. The full process takes 30–60 minutes. Read each step carefully before proceeding.

⚠

Before You Begin

Make sure you have everything you need before starting.

⛔

This process will completely erase your Chromebook

All data, apps, and settings will be permanently deleted. Back up anything important to Google Drive, a USB drive, or another device before you continue.

Prerequisites checklist

  • A supported Chromebook — check the Supported Devices page
  • A USB flash drive, 8 GB or larger (it will be erased)
  • A second computer (Windows, macOS, or Linux) to flash the USB
  • A Phillips #0 or #00 screwdriver (for write-protect removal on most devices)
  • A stable internet connection on the Chromebook
  • 30–60 minutes of uninterrupted time
  • Your Chromebook charger plugged in — keep it connected the entire time
1

Download CobaltOS & Flash Your USB Drive

Get the installation image and write it to a USB drive.

1

Download the CobaltOS ISO

Get the latest release from GitHub.

Download the latest CobaltOS ISO from the GitHub Releases page. Look for a file named something like cobaltos-x.x.x-amd64.iso.

After downloading, verify the SHA256 checksum to make sure the file wasn't corrupted during download:

Open PowerShell and run:

powershell 
Get-FileHash .\cobaltos-amd64.iso -Algorithm SHA256

Compare the output hash to the checksum listed on the Releases page.

bash 
shasum -a 256 ~/Downloads/cobaltos-amd64.iso
bash 
sha256sum ~/Downloads/cobaltos-amd64.iso
2

Flash the ISO to your USB drive

Write the image using Rufus, balenaEtcher, or dd.

⚠️

Do not open the ISO like a zip file

You must use a flashing tool. Simply copying files onto the USB will not work.

  1. Download Rufus — it's free, portable, no install needed.
  2. Plug in your USB drive.
  3. Open Rufus. Under Device, confirm your USB drive is selected.
  4. Click SELECT and choose the CobaltOS .iso file.
  5. Set Partition scheme → GPT.
  6. Set Target system → UEFI (non CSM).
  7. Click START.
  8. If asked about writing mode, choose Write in ISO Image mode.
  9. Click OK on the warning — this will erase the USB drive.
  10. Wait for it to finish, then click CLOSE.
  1. Download balenaEtcher.
  2. Open balenaEtcher.
  3. Click Flash from file and select the CobaltOS .iso.
  4. Click Select target and choose your USB drive.
  5. Click Flash! and wait for it to complete.
  6. You may be asked for your password — this is normal for disk writes.
  1. Find your USB drive device name:
    bash 
    lsblk
    Look for a drive the size of your USB (e.g. /dev/sdb).
  2. Unmount it:
    bash 
    sudo umount /dev/sdX*
  3. Flash it (replace sdX with your device):
    bash 
    sudo dd if=~/Downloads/cobaltos-amd64.iso of=/dev/sdX bs=4M status=progress conv=fdatasync
  4. Wait for the command to return to the prompt, then run sync and safely remove the USB.
2

Enable Developer Mode

Unlock low-level access — required before changing firmware.

💡

This is normal and expected

Developer Mode is an official Google feature, not a hack. It just unlocks access that Google hides by default. It will wipe local data on the device.

3

Enter Recovery Mode

Power off your Chromebook completely first.

With your Chromebook powered off:

  1. Hold Esc + Refresh ↻ + Power simultaneously.
  2. Keep holding until you see a screen that says "ChromeOS is missing or damaged" — you are in Recovery Mode. ✅
📱

Tablet-form Chromebooks

Hold Volume Up + Volume Down + Power instead.

4

Enable Developer Mode

Takes 5–10 minutes. The device will wipe itself.

  1. On the Recovery Screen, press Ctrl + D.
  2. A screen will appear asking "Turn OS verification OFF".
  3. Press Enter to confirm (or press the physical button shown on newer devices).
  4. The Chromebook will make a loud beep and begin transitioning to Developer Mode.
  5. A progress bar will appear — this takes 5–10 minutes.
  6. The device will reboot automatically when done.
⚠️

"OS verification is OFF" screen on every boot

After enabling Developer Mode, you will see this screen every time you boot. This is normal. Press Ctrl + D to continue booting quickly, or wait 30 seconds for it to continue automatically.

3

Disable Firmware Write Protection

Required before flashing new firmware. Choose the method for your device.

ChromeOS firmware is write-protected by hardware to prevent accidental or malicious modification. You must disable this before you can flash new firmware. Check the Supported Devices page to see which method your device uses.

5

Remove Write Protection

Use Method A (WP screw) or Method B (battery disconnect) depending on your device.

  1. Power off the Chromebook completely and unplug the charger.
  2. Flip the Chromebook over and remove the bottom cover screws (typically Phillips #0 or #00 — check under rubber feet for hidden screws).
  3. Carefully pry off the bottom cover with a spudger or guitar pick.
  4. Locate the write-protect screw on the motherboard. It is usually:
    • Near the SSD or RAM
    • A different color (silver or gold) than surrounding screws
    • Sometimes labeled "WP" on the board
    Check docs.mrchromebox.tech for your specific board's screw location.
  5. Remove the WP screw and keep it somewhere safe.
  6. Reassemble the Chromebook (you can leave the WP screw out permanently — it's not needed for normal operation).

Some newer Chromebooks with CR50/GSC security chips use battery-disconnect instead of a WP screw:

  1. Power off completely and unplug the charger.
  2. Remove the bottom cover (as above).
  3. Locate the battery connector on the motherboard.
  4. Carefully disconnect the battery cable from the board.
  5. Wait 30 seconds.
  6. Reconnect the battery.
  7. Reassemble the Chromebook.
✅

Write protection is now disabled

You will not need to do this again unless you want to restore the original firmware.

4

Flash the UEFI Firmware

Replace the stock ChromeOS firmware with MrChromebox's UEFI Full ROM.

You are replacing the stock ChromeOS firmware with a proper UEFI firmware using MrChromebox's open-source Firmware Utility Script. This is what allows CobaltOS (and any standard OS) to boot on your Chromebook.

6

Boot into ChromeOS

You don't need to sign in — Guest mode works fine.

  1. Boot the Chromebook. You'll see the "OS verification is OFF" screen — press Ctrl + D.
  2. Wait for ChromeOS to load to the login screen.
  3. Connect to WiFi (required for the firmware script).
  4. Click "Browse as Guest" — you do not need to sign into a Google account.
7

Open a Terminal

Access the ChromeOS developer shell.

  1. Press Ctrl + Alt + T to open the ChromeOS terminal (crosh).
  2. Type the following and press Enter to get a full Linux shell:
    crosh 
    shell
8

Run the MrChromebox Firmware Utility Script

Downloads and launches the firmware tool automatically.

bash 
cd; curl -LO https://mrchromebox.tech/firmware-util.sh && sudo bash firmware-util.sh

The script will download and launch automatically, showing a menu of options.

9

Back Up Your Stock Firmware

Strongly recommended — this is your safety net.

  1. In the firmware script menu, select "Backup Firmware" (if available for your device).
  2. When prompted, save the backup to a USB drive.
💾

Keep this backup somewhere safe

If anything goes wrong and you ever want to return to ChromeOS, this backup is how you restore it. Without it, recovery is still possible but more involved.

10

Install UEFI Full ROM Firmware

Takes about 2 minutes. Do not interrupt this step.

  1. In the script menu, select "Install/Update Full ROM Firmware (UEFI)".
  2. Type y and press Enter when asked to confirm.
  3. The script will download and flash the firmware — this takes about 2 minutes.
  4. When done, the script will tell you to reboot.
⛔

Do not close the lid or unplug power during flashing

If the process is interrupted, the device may not boot. Keep your Chromebook plugged into power the entire time.

11

Reboot into UEFI

Confirm the new firmware is working.

  1. Remove any USB drives currently plugged in.
  2. Type reboot in the terminal, or close and reopen the lid:
    bash 
    reboot
  3. The Chromebook will reboot. You will not see the "OS verification" screen anymore. Instead, you will see a standard UEFI boot screen (possibly a brief blank screen or coreboot splash).
✅

UEFI firmware is installed!

The absence of the ChromeOS "OS verification" screen confirms the new firmware is working correctly.

5

Install CobaltOS

Boot from your USB drive and run the installer.

12

Boot from the USB Drive

Insert the CobaltOS USB you flashed in Phase 1.

  1. Insert the CobaltOS USB drive into your Chromebook.
  2. Power on the Chromebook.
  3. Immediately press Esc (or F2 / F10 — varies by device) to open the UEFI boot menu.
  4. You should see your USB drive listed — select it and press Enter.
  5. CobaltOS will boot to the live session. You can try it out before installing.
💡

If you don't see the boot menu

Try pressing Esc repeatedly right as the device powers on. If you see a black screen, wait 10–15 seconds — some devices take a moment to POST.

13

Launch the CobaltOS Installer

Find it on the desktop or in the app menu.

  1. Once the live session loads, you will see the CobaltOS COSMIC desktop.
  2. Double-click the "Install CobaltOS" icon on the desktop, or find it in the application menu.
  3. The cobalt-installer will launch.
14

Follow the Installer

The installer walks you through 8 simple steps.

💡

GUI and TUI modes

The graphical installer (cobalt-installer) opens by default. If you prefer a keyboard-driven interface, run cobalt-installer --tui from a terminal.

  1. Welcome — Brief overview screen. Click Next to begin.
  2. Device Check — The installer automatically detects your Chromebook model and confirms UEFI firmware, RAM, and disk compatibility. Any issues (missing UEFI, low RAM) are flagged here before you proceed.
  3. Disk Setup — Three choices to make:
    • Target disk — All detected disks are listed with model and size. Select the one to install CobaltOS on. All data on it will be erased.
    • Filesystem — ext4 (recommended — fast, widely supported) or btrfs (adds transparent zstd:3 compression and @ / @home / @snapshots subvolumes used by the update rollback system).
    • Partitioning mode — Guided (recommended) uses the entire disk: 512 MiB EFI + all remaining as root. Manual lets you specify the EFI size in MiB and root size in GiB (leave root at 0 to use all remaining space). In the TUI, press m to toggle mode, e to edit EFI size, r to edit root size.
  4. Location — Enter your locale (e.g. en_US) and timezone (e.g. America/New_York).
  5. Account — Create your Linux username, password, and hostname. The username must be lowercase with no spaces. The password must be at least 6 characters.
  6. Confirm — Review your choices: disk, partitioning mode, filesystem, locale, timezone, username, and hostname. This is your last chance to go back before data is erased. Click Install Now (or press Enter in TUI).
  7. Installing — Sit back! The installer runs the full debootstrap pipeline: partitioning → mounting → debootstrap → kernel → bootloader → timezone → locale → user account → hardware probe → services → reboot prompt. This takes about 5–10 minutes depending on your disk speed.
  8. Done — Click "Restart Now" and remove the USB drive when prompted.
15

First Boot — OOBE & Welcome

CobaltOS guides you through hardware setup and personalisation on first login.

A — Automatic hardware configuration

On first boot, cobalt-hardware-probe detects your exact Chromebook board and automatically applies:

  • Keyboard remapping — Top row (F1–F10 / brightness / volume) and Search → Caps Lock via keyd
  • Audio UCM profile — Board-specific ALSA/PipeWire routing so speakers and microphone work correctly
  • Touchpad sensitivity — libinput quirks tuned per board (lighter for smaller trackpads, heavier for Pixelbook-class)
  • 3-finger workspace gestures — Writes COSMIC compositor gesture config for swipe-left/right workspace switching
  • HiDPI scaling — Detected from DMI/display info and applied to COSMIC

B — OOBE (Out-of-Box Experience)

cobalt-oobe launches automatically before the COSMIC desktop loads. It presents a 6-page wizard:

  1. Welcome — Introduction to CobaltOS
  2. Connect — WiFi / network setup
  3. Timezone — Pick from 15 common zones
  4. Privacy — Enable or disable analytics & location services (both off by default)
  5. Account — Set your display name (shown in the desktop panel)
  6. Ready — Confirm and launch the desktop

When OOBE finishes, cobalt-first-boot.service applies your choices system-wide: timezone via timedatectl, locale via locale-gen + localectl, display name via chfn, and COSMIC dark/light theme. It's idempotent — it only runs once, then leaves a marker so it never runs again.

C — Welcome Wizard

After the desktop loads, cobalt-welcome opens automatically with a 6-page wizard:

  1. Welcome — Tips for new users
  2. Appearance — Light, Dark, or Cobalt Blue theme (applies live to COSMIC)
  3. Locale — Select from 23 locales in a scrollable list
  4. Browser — Firefox (default), Chromium, Brave, or None
  5. Apps — Choose from 10 curated Flatpak apps: VS Code, GIMP, Inkscape, VLC, OBS Studio, LibreOffice, Steam, Signal, Obsidian, Kdenlive
  6. Finish — Your theme, locale, and browser preferences are saved; selected apps queue for installation

Selected Flatpak apps install silently in the background via cobalt-flatpak-install.service — you can use the desktop immediately without waiting for downloads to complete.

✅

Your system is ready

After the welcome wizard, CobaltOS is fully configured for your Chromebook. cobalt-update will check for updates automatically every 6 hours and notify you when new packages are available.

🎉

Welcome to CobaltOS!

Your Chromebook is now running a full, free, fast Linux desktop. Explore the COSMIC desktop, install apps from the App Center, and enjoy your device — no Google account required.

?

Troubleshooting

Common issues and how to fix them.

  • Wait 15 seconds. If nothing happens, try pressing Esc or F2 at startup to access the UEFI boot menu and manually select the USB drive. Make sure the USB was flashed correctly using GPT partition scheme and UEFI mode.

  • Your write-protect screw may not have been fully removed, or your device uses the battery-disconnect method. Re-check Phase 3. Ensure the bottom cover is fully reassembled before trying again (the WP screw engages a contact on the board, so the cover needs to be on).

  • This is rare. Boot into CobaltOS and open a terminal via the on-screen keyboard (touch or mouse). Run:

    bash 
    sudo systemctl restart cobalt-hardware-probe

  • Some Chromebook WiFi chips require non-free firmware. Connect via USB Ethernet or tethering, then run:

    bash 
    sudo apt install firmware-iwlwifi firmware-atheros firmware-misc-nonfree

    Then reboot.

  • Chromebook audio uses complex DSP routing. Run the hardware probe fix in a terminal:

    bash 
    cobalt-hardware-probe --fix-audio

    If that doesn't help, check the GitHub Issues page for your board name.

  • Some Chromebooks with NVMe drives need the nvme kernel module loaded manually. In the live session, open a terminal and run:

    bash 
    sudo modprobe nvme

    Then relaunch the installer.

  • If you saved a firmware backup in Step 9, you can restore it using the MrChromebox script. Visit docs.mrchromebox.tech for full recovery instructions.

    If you did not back up, use the Chromebook Recovery Utility from another computer to restore stock firmware.

  • CobaltOS automatically rolls back if an upgrade fails mid-run. If you need to trigger a rollback manually, open a terminal and run:

    bash 
    cobalt-update rollback

    This restores the dpkg package state to the snapshot taken before the last upgrade. If you installed CobaltOS on a btrfs filesystem, a read-only subvolume snapshot was also created at /.snapshots/pre-update-<timestamp>. You can boot from it via the systemd-boot menu if needed.

  • If you chose btrfs during installation, CobaltOS automatically creates a read-only snapshot of the root subvolume before every upgrade. To list available snapshots:

    bash 
    sudo btrfs subvolume list /.snapshots

    To mount and inspect a snapshot:

    bash 
    sudo mount -o subvol=@snapshots /dev/mmcblk0p2 /mnt/snapshot
# browse /mnt/snapshot, then unmount:
sudo umount /mnt/snapshot

    Up to 3 pre-upgrade snapshots are kept; older ones are pruned automatically.

  • Run the hardware probe gesture fix to regenerate the COSMIC and Xorg gesture config for your board:

    bash 
    cobalt-hardware-probe --fix-gestures

    For general touchpad issues (scroll speed, tap-to-click, palm rejection):

    bash 
    cobalt-hardware-probe --fix-touchpad

    Log out and back in for the changes to take effect in the Wayland session.

  • You can launch them manually from a terminal at any time:

    bash 
    # OOBE (system setup — timezone, privacy, account)
cobalt-oobe

# Welcome wizard (appearance, locale, browser, apps)
cobalt-welcome

    To re-run cobalt-first-boot (which applies OOBE settings system-wide), remove the completion marker and start the service:

    bash 
    rm ~/.config/cobaltos/.first-boot-done
systemctl --user start cobalt-first-boot.service
← Previous Supported Devices