Skip to main content

usbuntu: a full Ubuntu on a USB stick, straight from the terminal

CI Release 1.2.1 PyPI usbuntu Python 3.14 and 3.15 Ubuntu 24.04 and later Secure Boot on or off Claude Code plugin mypy strict MIT licence Stars

Install a complete, bootable Ubuntu system on a USB stick from an ISO, straight from the terminal.

usbuntu is not dd. A raw ISO copy gives you a live session that forgets everything. A normal install needs an installer boot first. usbuntu skips both: it unpacks the ISO's own system layers straight onto the stick, installs the bootloader, and hands you a full Ubuntu that keeps its files, takes updates and installs software. A portable machine in your pocket.

uv tool install usbuntu
usbuntu devices
sudo usbuntu install ubuntu-26.04.1-desktop-amd64.iso --username you

Type WIPE at the prompt, wait about twenty minutes, reboot, press F12 and pick the stick.

Install

It needs Python 3.14 or later on any Linux machine that can mount things; Ubuntu, Debian and friends work out of the box, and uv fetches a Python if yours is older.

uv tool install usbuntu

pip install usbuntu and pipx install usbuntu work too.

Use

usbuntu devices                                                   # which disks are safe targets, no root needed
sudo usbuntu install ubuntu.iso --username you --dry-run          # show the plan, touch nothing
sudo usbuntu install ubuntu.iso --username you                    # everything else optional
sudo usbuntu inspect ubuntu.iso                                   # which layers an ISO would install
sudo usbuntu verify /dev/sda                                      # check a stick's boot chain

Every variable:

Variable Flag Default
Account name --username you required
Starting password --password secret generated, printed at the end
Force a new password at first login --no-force-password-change forced
Machine name --hostname my-stick usb-ubuntu
Full or reduced desktop --flavor full|minimal full
Language layers --language en en
Snap --remove-snap kept
Extra apt packages --packages curl,vim,git none
Bundled extras --with opencode, --with claude-code, --with build-tools none
Target disk --device /dev/sda the one safe disk found
Unattended --yes asks for WIPE

The password is written to the new system through a pipe, never to a file and never to a log, and a fresh install always asks for its own password at first login.

Safe by default

usbuntu will not wipe a disk that is not on USB, not removable, smaller than 8 GiB, or that holds the running system, so a machine that boots from a stick cannot be told to erase itself. With more than one safe disk it refuses to guess. usbuntu devices shows the same verdicts before you start:

$ usbuntu devices
/dev/nvme0n1    476.9 GiB  Example NVMe SSD      refused: not on USB; not removable; holds the running system (/)
/dev/sdb         14.3 GiB  Example USB stick     ACCEPTED

With an AI agent

usbuntu ships a skill that teaches an agent to drive it safely: never pick the disk silently, leave WIPE to you, never echo a password, read the log after a failure. Install it as a Claude Code plugin:

/plugin install usbuntu --marketplace jpsanders/usbuntu

On Claude Code before 2.1.275: /plugin marketplace add jpsanders/usbuntu, then /plugin install usbuntu@usbuntu. Other agents read skills/usbuntu/SKILL.md as it is. usbuntu devices --json gives an agent the disk verdicts as data, and usbuntu guide prints the whole manual.

There is no MCP server, on purpose: erasing a disk as root should stay a decision a person makes at a terminal.

How it works

Ubuntu desktop ISOs since 24.04 ship as a stack of squashfs overlay layers: a minimal base, a standard full desktop layer, thin language layers, and two kinds of layer that must never reach an installed stick. usbuntu mounts the right chain with overlayfs and copies the merged view over with rsync -aHAX, the same path the official installer takes, minus the installer.

ISO  ->  squashfs layer chain  ->  overlayfs merged view  ->  rsync  ->  stick
                                                          chroot: apt, account, GRUB
                                                          ESP: signed shim + signed GRUB, md5 verified

Every step in that pipeline exists because its absence broke a real install:

  1. Layer selection. The live layer only belongs to the live session. The enhanced-secureboot layers whiteout the deb kernel from /boot, because Ubuntu 26.04 can hand the boot chain to snapd (boot-managed-by-snapd). usbuntu keeps the classic GRUB path and always excludes both.
  2. overlayfs, not unsquashfs. Extracting stacked layers one by one with unsquashfs dies on hardlinks across layers. Overlayfs consumes whiteouts correctly and rsync preserves what it merges.
  3. A truthful /etc/mtab. Chrooted GRUB tools read the host's mount table and probe the wrong root. usbuntu writes a real mtab naming the stick before update-grub runs.
  4. The signed binaries, verified. grub-install in a chroot can silently write its own unsigned GRUB image to EFI/BOOT/BOOTX64.EFI, which boots to a bare grub> prompt. After every install usbuntu copies the genuine signed shim and GRUB from the target's own packages and verifies them with md5. sudo usbuntu verify /dev/sda runs the same checks again on any stick, any time.

Notes

  • The stick must be at least 8 GiB and the machine must boot with UEFI. The result boots with Secure Boot on or off, because the chain is the same signed shim Ubuntu ships.
  • --remove-snap purges snapd and holds it back. Firefox and the Snap Store go with it; install a deb browser in --packages if you want one.
  • A failed run costs little: the completed system copy is marked on the stick and the next run resumes from it instead of copying 7 GB again. Stop the desktop's automount monitor and unmount the leftovers first; usbuntu guide has the exact commands.
  • Every root run appends a log to /var/log/usbuntu.log: the commands, the phase messages, the full traceback, and, when the chroot fails, the real apt error. Diagnose from there instead of exit codes.
  • The pipeline was verified end to end against the 26.04.1 desktop ISO on a 16 GiB SanDisk Cruzer Blade.

The manual

usbuntu guide prints the full manual for people and agents, usbuntu man shows it as a man page, and usbuntu man --install makes man usbuntu work. The source is docs/MANUAL.md.

Develop

make init-dev
make checks

make checks runs isort, black, editorconfig-checker, darglint, flake8, mypy in strict mode, bandit, the man page check and pytest with coverage, the same as CI. Tests never touch a real disk. See CONTRIBUTING.md and AGENTS.md.

Star history

Star history of jpsanders/usbuntu

Licence

MIT. Made by James Phillip Sanders.

Metadata

Release files for usbuntu 1.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for usbuntu 1.2.1
File Size Uploaded Provenance Actions
usbuntu-1.2.1.tar.gz 186.1 kB With provenance Details for usbuntu-1.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for usbuntu 1.2.1
File Interpreter ABI Platform Actions
usbuntu-1.2.1-py3-none-any.whl Python 3 none any Details for usbuntu-1.2.1-py3-none-any.whl

Total release size: 221.7 kB

Release files / usbuntu-1.2.1.tar.gz

Download URL usbuntu-1.2.1.tar.gz
Size 186.1 kB
Tags Source
SHA-256 checksum
How to use checksums
95a6b7bcddb8ecb4cecf7fa6e37c39e879dc4ca2159f988037a1a65b2fc803de
BLAKE2b-256 checksum
How to use checksums
22a0a118d2fc6c60d7cbab6d4c403410d702118e7f8292d31610f2ecbb85a7d2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / usbuntu-1.2.1-py3-none-any.whl

Download URL usbuntu-1.2.1-py3-none-any.whl
Size 35.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8cddb50c8027c3547746e1565b79118a1a923e45a1e012a062edd6872871ac3a
BLAKE2b-256 checksum
How to use checksums
3a4b5402b60639ef5fe2c18c04c65f616ef80617c059860200ee41d3a9d6d971
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for usbuntu 1.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for usbuntu-1.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page