Skip to main content

AmiFUSE

Mount Amiga filesystem images on macOS/Linux/Windows using native AmigaOS filesystem handlers via FUSE.

AmiFUSE runs actual Amiga filesystem drivers (like PFS3) through m68k CPU emulation, allowing you to read Amiga hard disk images without relying on reverse-engineered implementations.

Read-write access is supported on macOS and Linux. Writable Windows mounts remain experimental because of the known Windows write limitations below. Mounts are read-only by default on every platform; use --write to enable writes.

amifuse

Requirements

  • macOS: macFUSE 5.3.3 or newer
  • Linux: FUSE for Linux
  • Windows: WinFSP
  • Python 3.11+
  • 7z: Required for make unpack (install via brew install p7zip on macOS)
  • A filesystem handler: e.g. pfs3aio (or use make download)

Installation

The bootstrap scripts handle everything: Python, FUSE provider, virtual environment, pip dependencies, and amifuse doctor --fix.

# Clone the repository with submodules
git clone --recursive https://github.com/reinauer/AmiFUSE.git
cd AmiFUSE

Windows (PowerShell):

.\tools\install-windows.ps1

macOS / Linux:

./tools/install.sh

From source (for development)

Use this if you are contributing to the project or need a custom setup.

git clone --recursive https://github.com/reinauer/AmiFUSE.git
cd AmiFUSE

# Or if already cloned, initialize submodules
git submodule update --init

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

pip install -e './amitools[vamos]'   # Install amitools from submodule (includes machine68k)
pip install -e .                     # Install AmiFUSE
pip install -e '.[windows]'         # Windows only: adds pystray + Pillow for tray/shell integration

The Windows installer downloads tested wheels built from upstream machine68k 0.5.0 for Python 3.11--3.15. Direct pip installations can now use the upstream machine68k 0.5.1 wheels published on PyPI for Windows x64 and those Python versions. Other platform/Python combinations without a matching wheel may need a native compiler.

macOS-specific

Install macFUSE 5.3.3 or newer from https://osxfuse.github.io/ or via Homebrew/MacPorts. Earlier releases can crash because they initialize DiskArbitration and CoreFoundation state before daemonizing:

# Homebrew
brew install --cask macfuse

# MacPorts
port install macfuse +fs_link

You may need to reboot and allow the kernel extension in System Preferences > Security & Privacy.

Linux-specific

# Debian/Ubuntu
sudo apt install fuse libfuse-dev

# Fedora
sudo dnf install fuse fuse-devel

Running from source (without installing)

To run AmiFUSE directly from a local checkout (useful for development/debugging):

python3 -m amifuse mount disk.hdf

Quick Start

To download a test PFS3 disk image and the pfs3aio handler:

make download   # Downloads pfs.7z and pfs3aio to Downloads/
make unpack     # Extracts pfs.hdf and copies pfs3aio to current directory

Then mount with:

# macOS: auto-mounts to /Volumes/<partition_name>, uses embedded driver from RDB
amifuse mount pfs.hdf

# Linux: requires explicit mountpoint
mkdir -p ./mnt
amifuse mount pfs.hdf --mountpoint ./mnt

# Stay attached to the terminal if you want Ctrl+C to unmount
amifuse mount pfs.hdf --interactive

To compare this checkout against ../amifuse-0.2 using the bundled pfs.hdf and pfs3aio, run:

make bench-pfs

This benchmark bypasses macFUSE and measures the handler startup time, a full recursive directory walk equivalent to find, and a small set of file reads. You can override the defaults with PFS_BENCH_BASELINE, PFS_BENCH_IMAGE, PFS_BENCH_DRIVER, and PFS_BENCH_REPEAT.

Usage

See shared disk sessions for image locking, ownership and device compatibility policies.

amifuse uses subcommands for different operations:

amifuse inspect <image>                    # Inspect RDB partitions
amifuse mount <image>                      # Mount a filesystem
amifuse unmount <mountpoint>               # Unmount a filesystem
amifuse format <image> <partition> [name]  # Format a hard disk partition
amifuse format <floppy.adf> <name>         # Format a floppy image
amifuse doctor                             # Check dependencies and configuration
amifuse register                           # Add Windows Explorer context menu entries
amifuse unregister                         # Remove Windows Explorer context menu entries

Inspecting Disk Images

View partition information and embedded filesystem drivers:

# Show partition summary
amifuse inspect /path/to/disk.hdf

# Show full partition details
amifuse inspect --full /path/to/disk.hdf
Argument Description
image Path to the RDB image file
--block-size Block size in bytes (default: auto-detect or 512)
--full Show full partition details

Mounting Filesystems

amifuse mount /path/to/disk.hdf
Argument Required Description
image Yes Path to the Amiga hard disk image file
--driver No Path to filesystem handler binary (default: RDB, your drivers folder, then the bundled FastFileSystem for DOS0-7; see Bundled FastFileSystem)
--mountpoint macOS/Windows: No, Linux: Yes Mount location (macOS: /Volumes/<partition>, Windows: first free drive letter)
--partition No Partition name (e.g., DH0) or index (default: first partition). A repeated name is renamed as AmigaOS renames it, so a second DH0 is DH0.1; a partition marked not to mount takes its name after those that mount
--block-size No Override block size (default: auto-detect or 512)
--volname No Override the volume name shown in Finder
--daemon No Detach after mounting (default on macOS/Linux)
--interactive / --foreground No Stay attached to the terminal; Ctrl+C unmounts
--debug No Enable debug logging of FUSE operations
--profile No Enable cProfile profiling and write stats to profile.txt on exit
--write No Enable read-write mode (experimental on Windows)
--icons No Convert Amiga .info icons to native icons (experimental, macOS only)

Mount lifecycle:

  • macOS and Linux default to daemon mode. The mount keeps running after the command returns, and you normally tear it down with amifuse unmount <mountpoint>.
  • --interactive / --foreground keeps AmiFUSE attached to the terminal. Use this for debugging or when you want Ctrl+C to unmount from the same shell.
  • Windows defaults to daemon mode. Double-click .hdf/.adf files to mount and open Explorer (requires amifuse register). Unmount from the system tray icon or with amifuse unmount <drive>:. The WinFSP "Eject" action does not perform a clean unmount — use the tray or CLI instead.
  • --profile implies interactive mode.

Physical disks on Windows

With WinFsp installed, AmiFUSE can open a USB CF/SD card or other physical disk directly using its \\.\PhysicalDriveN device name. Open PowerShell as Administrator, then identify the disk by its name and size:

Get-Disk | Format-Table Number, FriendlyName, BusType, Size

Find the CF card by its FriendlyName, USB bus type, and Size. The Number column determines the device path: disk 2 is \\.\PhysicalDrive2, disk 3 is \\.\PhysicalDrive3, and so on. If you are unsure which disk is the card, compare the command's output with the reader unplugged and then plugged in, before mounting it.

For example, if the CF card is disk 2, inspect its Amiga partitions and mount DH0 at an unused drive letter:

amifuse inspect '\\.\PhysicalDrive2'
amifuse mount '\\.\PhysicalDrive2' --partition DH0 --mountpoint R:
amifuse unmount R:

The single quotes are PowerShell quoting; they are not part of the device name.

Elevated drive-letter mounts use the Windows mount manager, making R: visible in normal Explorer windows and unelevated applications. This also applies to image files mounted from an Administrator shell. Ordinary unelevated image mounts keep their existing per-session drive letters. You can explicitly request the global form with --mountpoint '\\.\R:'; this requires Administrator privileges. Both forms refer to the same drive for amifuse unmount.

The drive letter must be unused in both the Administrator shell and the normal desktop session. An elevated process cannot detect drive mappings that exist only in the normal session, such as network or subst drives; those mappings take precedence over a global drive with the same letter in that session, so Explorer would continue to show the existing drive.

Run amifuse unmount R: from an Administrator shell for an elevated mount. The normal desktop tray cannot reliably discover or unmount elevated mounts, even though Explorer can access their files. Global visibility does not change file permissions or grant the tray access to elevated control events.

On Windows, the mount root grants write access only to the mounting account. If you elevate using a different administrator account, your normal desktop account can read and list the mounted files but does not gain root write access.

Mounts are read-only by default. To enable writes to the card itself:

amifuse mount '\\.\PhysicalDrive2' --partition DH0 --mountpoint R: --write

Use the actual disk number and partition name from the commands above. Cancel any Windows prompt to initialize or format the Amiga disk.

AmiFUSE holds a global Windows process lock for the physical disk until its last stream closes. This excludes other AmiFUSE/vamos sessions even when a disk driver does not enforce exclusive handle sharing. It does not exclude unrelated raw-disk tools. Writable mounts also lock and dismount Windows volumes identified on that disk; close applications using those volumes first. If a required lock fails, the mount fails before AmiFUSE writes to the disk. Before unplugging the card, run amifuse unmount R: from an Administrator shell. This requests WinFsp shutdown and waits for handler flushing and disk cleanup. A timeout or flush failure is reported as an error; the unmount request never falls back to force-killing the process. Check the mount log and wait for a successful unmount before removing the card. On Windows, flushing the root directory or the volume waits for pending close callbacks; a flush of any other directory waits for nothing, so do not rely on flushing a file's own folder. Neither flushes data buffered by an open file: applications must flush each open file itself (for example, with FlushFileBuffers) before relying on its data being stored. Closing a file is asynchronous; a successful close alone does not mean its pending metadata has reached the image. No extra pywin32 dependency is required.

When running this change from source, install the accompanying amitools checkout as well as AmiFUSE into your Python environment:

python -m pip install -e './amitools[vamos]'
python -m pip install -e '.[windows]'

The upstream amitools[vamos]>=0.9.0 dependency includes physical-disk support, partition range locks, and the scheduler runtime, and installs machine68k 0.5.0 or newer and greenlet. Plain pip install amitools omits these optional vamos dependencies. The source installation above is only needed to test unreleased amitools changes.

Formatting

amifuse format erases a partition or a floppy image without asking, using the filesystem driver mount would use. Name a partition on a hard disk image, and only the new volume name for a floppy image, which has no partitions:

amifuse format disk.hdf DH0 Work
amifuse format floppy.adf Work
amifuse format floppy.adf Work --dos-type DOS3

A floppy image is a file of 901120 (DD) or 1802240 (HD) bytes. format keeps the DOS type in its block 0 unless --dos-type (DOS0 to DOS7) gives another. An all-zero file of those sizes, for example from dd if=/dev/zero of=floppy.adf bs=512 count=1760, has no DOS type and gets DOS0 unless --dos-type says otherwise. Only format accepts such a file: format it before using it with any other command. A file of those sizes with an RDB is treated as a hard disk image; one with other contents is formatted only with --dos-type, since nothing shows that it holds a floppy.

Diagnosing Issues

amifuse doctor checks that all dependencies (Python, FUSE provider, handlers) are correctly installed and configured.

amifuse doctor            # Human-readable report
amifuse doctor --json     # Machine-readable JSON output
amifuse doctor --fix      # Auto-fix what it can (PATH, shell registration)

Examples

# macOS: Mount using embedded filesystem driver from RDB (simplest)
amifuse mount disk.hdf

# macOS: Mount with explicit driver
amifuse mount pfs.hdf --driver pfs3aio

# Mount a specific partition by name
amifuse mount multi-partition.hdf --partition DH0

# Mount a specific partition by index
amifuse mount multi-partition.hdf --partition 2

# Linux: Explicit mountpoint required
mkdir -p ./mnt
amifuse mount disk.hdf --mountpoint ./mnt

# Mount an ADF floppy image (uses the bundled FastFileSystem for DOS0-7)
amifuse mount workbench.adf

# Enable native icons (macOS only, converts Amiga .info files)
amifuse mount disk.hdf --icons

# Keep the mount attached for debugging
amifuse mount disk.hdf --interactive

# Browse the filesystem
ls /Volumes/PDH0   # macOS
ls ./mnt           # Linux

# Unmount a daemon mount when done
amifuse unmount /Volumes/PDH0   # macOS
amifuse unmount ./mnt           # Linux

Different, nonoverlapping RDB partitions in one image can be mounted in separate sessions concurrently, including with --write. Read-only sessions can also share the same partition. A writable session excludes all other access to its partition, and whole-image sessions exclude partition mounts. Each handler is restricted to its selected partition; physical disks, ADFs, and ISOs retain whole-device or whole-image locking.

Without --partition, a session uses the first partition, so it can run alongside sessions on other partitions. Whole-image sessions are ADF, ISO and physical-disk sessions, and sessions from tools that lock the entire file. On platforms without byte-range locks (for example 32-bit Linux and the BSDs), every session locks the whole image.

Additional Tools

rdb-inspect

Inspect RDB (Rigid Disk Block) images to view partition information and embedded filesystem drivers.

# Show partition summary
rdb-inspect /path/to/disk.hdf

# Show full partition details
rdb-inspect --full /path/to/disk.hdf

# Output as JSON
rdb-inspect --json /path/to/disk.hdf

# Extract embedded filesystem driver #0 to a file
rdb-inspect --extract-fs 0 --out pfs3.bin /path/to/disk.hdf
Argument Description
image Path to the RDB image file
--block-size Block size in bytes (default: auto-detect or 512)
--full Show full partition details
--json Output parsed RDB as JSON
--extract-fs N Extract filesystem entry N (0-based), the report's FS #N, to a file
--out Output path for extracted filesystem (default: auto-derived)

driver-info

Inspect Amiga filesystem handler binaries to verify they can be relocated and display segment information.

# Inspect a filesystem handler
driver-info pfs3aio

# Use a custom base address
driver-info --base 0x200000 pfs3aio
Argument Description
binary Path to the filesystem handler binary
--base Base address for relocation (default: 0x100000)
--padding Padding between segments when relocating

Supported Image Formats

  • HDF/RDB - Hard disk images with Rigid Disk Block. Filesystem drivers can be embedded in the RDB or specified via --driver. An FFS/OFS partition whose RDB has no driver for its DOS type uses the bundled FastFileSystem.
  • Emu68-style MBR images - Disk images with MBR partition table containing an RDB partition, as used by Emu68 on Raspberry Pi.
  • ADF - Amiga Disk File floppy images (DD and HD). ADFs contain no driver, so DOS0-7 floppies use the bundled FastFileSystem unless your drivers folder holds your own. A blank file of a floppy's size can be formatted into one.

Supported Filesystems

Currently tested with:

  • FFS/OFS (Fast/Old File System) via the bundled FastFileSystem for DOS0-7, or your own L:FastFileSystem from Workbench (tested with 3.2), which wins when present
  • CDFileSystem via L:CDFileSystem from Workbench (tested with 3.2)
  • PFS3 (Professional File System 3) via pfs3aio handler
  • SFS (Smart File System 1.279) via SmartFileSystem handler
  • BFFS (Berkeley Fast File System) via Chris Hooper's BFFSFilesystem handler
  • ODFileSystem (Optical Disc Filesystem) via Stefan Reinauer's ODFileSystem handler

Other Amiga filesystem handlers may work but have not been tested. Reports are welcome.

Bundled FastFileSystem

AmiFUSE ships Stefan Reinauer's FastFileSystem (release v0.2, an early version) for FFS/OFS volumes that carry no driver of their own. It supports DOS0-DOS7, long file names included. Like the FastFileSystem of AmigaOS 3.2, it shortens a name longer than the volume takes (30 bytes, or 106 with long file names) whenever it creates, renames, opens or deletes a file. Two names that share their first 30 (or 106) bytes are therefore the same file: writing the second overwrites the first, and deleting either deletes it.

Without --driver, AmiFUSE picks the driver in this order:

  1. The driver in the RDB for the partition's exact DOS type. If that driver is damaged, AmiFUSE stops and asks for --driver instead of using another. It also stops when part of the RDB's driver list is unreadable and may hide the partition's driver. A driver the RDB holds for a different DOS type is not used, as on an Amiga, where the FFS in ROM then serves the partition.
  2. FastFileSystem in your drivers folder (%LOCALAPPDATA%\amifuse\drivers on Windows, ~/.local/share/amifuse/drivers elsewhere), for DOS0-DOS7. Place the one from AmigaOS 3.2 there to use it instead of the bundled one.
  3. The bundled FastFileSystem, for DOS0-DOS7.

The mount banner, amifuse doctor and amifuse inspect name the driver in use; inspect names it for an ADF and for each partition of a hard disk image.

The handler ships in amifuse/drivers/ as the release asset FastFileSystem.OS3, unchanged, with its licence (FastFileSystem.OS3.LICENSE, BSD-2-Clause) and provenance (FastFileSystem.OS3.json: repository, tag, commit, size, sha256, covered DOS types and the build). To move to a new release, replace the asset and the licence, and update the provenance file; the unit tests check that the three agree. Messages from doctor, inspect and failed mounts take the covered DOS types from the provenance file. If dos_types changes, also update the ranges written out in the --driver help in amifuse/fuse_fs.py and in this README (the --driver row, the ADF example, Supported Image Formats, Supported Filesystems and this section), and in TESTING.md; the unit tests check the help and the README against the provenance file.

Icon Support

The --icons flag enables conversion of Amiga .info icon files to native Finder icons:

  • Folder and file icons from .info files are displayed in Finder
  • Supports Traditional, NewIcons, and GlowIcons formats
  • The .info files are hidden in directory listings
  • Volume icons are displayed on the Desktop

*** This feature is experimental and macOS-only. ***

Windows Shell Integration

On Windows, AmiFUSE can integrate with Explorer for double-click mounting, right-click context menus, and a system tray mount manager.

Context menu registration

amifuse register      # Add "Mount with AmiFUSE" to .hdf/.adf context menus
amifuse unregister    # Remove the context menu entries

Registration writes to HKCU (current user only) — no administrator privileges are required.

After registering:

  • Double-click an .hdf or .adf file to mount it and open Explorer at the mounted drive
  • Right-click for "Mount with AmiFUSE" (read-only) or "Mount Read-Write with AmiFUSE"

Tray mount manager

When a filesystem is mounted in daemon mode on Windows, the amifuse-tray helper appears in the system tray. From the tray icon you can see active mounts and unmount them cleanly. Each mount shows its drive letter, image name, and provides Inspect/Unmount actions.

The tray requires optional dependencies: install them with pip install amifuse[windows] (provides pystray and Pillow).

Removing shell integration

amifuse unregister

Or use the installer's uninstall mode:

.\tools\install-windows.ps1 -Uninstall

Notes

  • The filesystem is mounted read-only by default; use --write for read-write access. Writable Windows mounts remain experimental.
  • macOS and Linux default to daemon mode; use --interactive if you want Ctrl+C to unmount from the same terminal
  • Use amifuse unmount <mountpoint> to tear down daemon mounts
  • Windows defaults to daemon mode; unmount via the system tray icon or amifuse unmount <mountpoint>
  • macOS Finder/Spotlight indexing is automatically disabled to improve performance
  • First directory traversal may be slow as the handler processes each path; subsequent accesses are cached
  • Above 16 MiB, amifuse write first copies its source to a temporary file, so a large write needs free space for the whole source in the temporary directory (TMPDIR, else TEMP or TMP; Windows normally sets TEMP) as well as room in the image. If it runs short, the write stops with "cannot copy the source to a temporary file" (HANDLER_ERROR with --json) before the image is touched. A temporary directory on tmpfs, as /tmp often is, also holds the copy in RAM. Setting TMPDIR to an existing directory on a larger disk gets around both.

Known Windows write limitations

Writable Windows mounts remain experimental while these WinFsp-related issues are open. Use read-only mounts for irreplaceable media, or work on a backup image when testing writes.

  • #424: deleting through a handle that renamed a file can delete a different file created at the old name when WinFsp delivers closes late. The proposed upstream fix, WinFsp #704, has not shipped.
  • #438: a delete-on-close open can incorrectly report success for a delete-protected object when another open handle previously renamed its object away from that name. The protected object remains on disk.
  • #437: WinFsp builds that include the proposed current-name fix need a corresponding AmiFUSE compatibility change. Do not assume a custom WinFsp build with that patch is safe with this release.

These limitations concern writable Windows mounts. They do not apply to the FUSE-free file commands, read-only mounts, or the macOS and Linux FUSE interfaces.

Metadata

Release files for amifuse 1.0.0

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

Source distribution (sdist)

Source distribution for amifuse 1.0.0
File Size Uploaded Provenance Actions
amifuse-1.0.0.tar.gz 1.4 MB With provenance Details for amifuse-1.0.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.7 MB

Release files / amifuse-1.0.0.tar.gz

Download URL amifuse-1.0.0.tar.gz
Size 1.4 MB
Tags Source
SHA-256 checksum
How to use checksums
cd5ed9681a9c20ec229129fba0100e17a84d70d2977a91dad77460625fbe87a7
BLAKE2b-256 checksum
How to use checksums
160fc2090f4a1d5e1ad8ceb68615e541df68d203816cd471d3bc67926b6895e0
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 16, 2026.

Transparency log

Release files / amifuse-1.0.0-py3-none-any.whl

Download URL amifuse-1.0.0-py3-none-any.whl
Size 299.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7f0ac309b082e45c1b7dc19e45f8938d537105263f4627507ed2585cb6cfa4ad
BLAKE2b-256 checksum
How to use checksums
bbdef0716c13f12c2cbbf5109965255a414581f7f288a1b5f0990ac80bb7cb6b
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 16, 2026.

Transparency log

Security for amifuse 1.0.0

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 amifuse-1.0.0.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 16, 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.

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