iso-scalpel/QUICKSTART.md

Quick Start

Install and run ISO Scalpel in under five minutes.

Prerequisite: Python 3.10+. Check with python3 --version.

Install

tar xzf iso-scalpel-1.1.0.tar.gz
cd iso-scalpel-1.1.0

python3 -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate

pip install -r requirements.txt

On Arch / Fedora / Debian 12+ (PEP 668 distros): do not run pip install against the system Python -- it will be refused with externally-managed-environment. Always use a project venv as shown above, install the distro packages (sudo pacman -S python-pyside6 python-pycdlib), or pipx install iso-scalpel once published. If you launch python main.py without dependencies installed, ISO Scalpel will detect your distro and offer the right install command.

On minimal Linux, also install the Qt runtime libraries:

sudo apt install libegl1 libgl1 libglib2.0-0 libfontconfig1 \
                 libdbus-1-3 libxkbcommon0 libxcb-cursor0

GUI

python main.py                     # empty window
python main.py my_image.iso        # open an image
python main.py --check-deps        # report any missing dependencies and exit
python main.py --no-install-deps   # never prompt to install missing deps

If a required Python package (PySide6, pycdlib) is missing when you launch the GUI, ISO Scalpel will print a clear, copy-pasteable message listing exactly what's missing and the right install command for your distro (e.g. pacman -S python-pycdlib on Arch, apt-get install python3-pycdlib on Debian/Ubuntu, dnf install python3-pycdlib on Fedora). When run from an interactive terminal it offers install strategies in order of lowest privilege first:

1. Project venv (recommended on PEP 668 distros like Arch): python -m venv .venv && .venv/bin/pip install ... -- no sudo, no system mutation. Afterwards run ./.venv/bin/python main.py.
2. Distro package manager with sudo (e.g. sudo pacman -S python-pycdlib): shown with the exact command first, runs only after you type y.
3. pip install --user --break-system-packages: last-resort override for PEP 668, only with explicit consent.

Note on pipx: pipx install pycdlib installs pycdlib into an isolated venv that exports only its CLI tools (pycdlib-explorer etc.) to your PATH. The Python module is not importable from your system interpreter, so ISO Scalpel will still report it as missing. For libraries, use a project venv or the distro package instead. For the ISO Scalpel application itself, you can pipx install iso-scalpel once it's published (see pyproject.toml).

Pass --no-install-deps to skip the prompts and just exit.

The window has two panes. By default the left pane is the filesystem and the right pane is the ISO image. Each pane has breadcrumb navigation, back/forward/up arrows, a filter box, and a tab bar. Press Ctrl+Shift+X to swap the panes.

Create an image

1. Image → New… (Ctrl+N).
2. Set the volume label.
3. Tick the extensions: Joliet, Rock Ridge, UDF.
4. Pick the ISO 9660 interchange level.
5. Click OK.

Add files

Drag files from the filesystem pane onto a directory in the ISO pane. Or select them and press Insert. Files are written into every enabled naming convention; ISO 9660 names are mangled to valid 8.3 with collision avoidance.

Extract

Select entries in the ISO pane and press Ctrl+E.

Make it bootable

Tools → Boot Image… (Ctrl+B). Pick a boot image, the platform ID (x86 / EFI), and the media type. The boot file is added to the image and the boot catalog is generated.

Compare two images

Tools → Compare Images… (Ctrl+D). Pick image A and image B, click Compare. The tree shows added (+), removed (-), modified (M), and unchanged (=) entries. File contents are not compared — only the filesystem structure.

CLI

python cli.py --help

Create an image

python cli.py new disc.iso -l MYDISC \
    --joliet 3 --rock-ridge 1.09 --udf 2.60 \
    --add readme.txt

List contents

python cli.py list disc.iso
python cli.py list disc.iso / --view udf
python cli.py list disc.iso -r        # recursive

Show metadata

python cli.py info disc.iso

Add to an image

python cli.py add disc.iso ./file.txt /
python cli.py add disc.iso ./folder /sub

Extract

python cli.py extract disc.iso /readme.txt ./out.txt
python cli.py extract disc.iso /sub ./out_dir

Remove an entry

python cli.py rm disc.iso /old.txt

Configure boot

python cli.py boot disc.iso --set boot.img --platform 0
python cli.py boot disc.iso --set efi.img --platform 0xEF
python cli.py boot disc.iso --clear

Diff two images

python cli.py diff old.iso new.iso
python cli.py diff old.iso new.iso --all

Scripting

The handler and diff engine are importable directly:

from iso_scalpel.iso_handler import IsoHandler, NewIsoOptions
from iso_scalpel.diff import diff_images, format_diff_text

iso = IsoHandler()
iso.new(NewIsoOptions(volume_label="BACKUP", udf="2.60", joliet=3))
iso.add_file("readme.txt", "/", iso.default_name_type())
iso.save("backup.iso")
iso.close()

# compare two images
a = IsoHandler(); a.open("old.iso")
b = IsoHandler(); b.open("new.iso")
print(format_diff_text(diff_images(a, b)))

Lint and tests

The project ships with a locked-in ruff configuration (PEP 8, SEI CERT, MISRA-aligned immutability, POSIX shebang discipline). Run both before pushing:

pip install -e '.[dev]'     # pytest + ruff
ruff check .                # must report "All checks passed!"
python -m pytest            # hermetic deps tests always run; GUI tests
                            # self-skip when PySide6 / pycdlib are absent

See README.md · Coding standards for the full rule set and the rationale behind each.

Where to go next

• README.md — full feature list and API reference
• BLOG.md — what's new in this release
• iso_scalpel/iso_handler.py — the core engine (read the docstrings)
• iso_scalpel/diff.py — the diff engine
• ~/.config/iso-scalpel/settings.json — application settings