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.
Requirements
- macOS: macFUSE 5.3.3 or newer
- Linux: FUSE for Linux
- Windows: WinFSP
- Python 3.11+
- 7z: Required for
make unpack(install viabrew install p7zipon macOS) - A filesystem handler: e.g. pfs3aio (or use
make download)
Installation
Quick install (recommended)
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/--foregroundkeeps AmiFUSE attached to the terminal. Use this for debugging or when you wantCtrl+Cto unmount from the same shell.- Windows defaults to daemon mode. Double-click
.hdf/.adffiles to mount and open Explorer (requiresamifuse register). Unmount from the system tray icon or withamifuse unmount <drive>:. The WinFSP "Eject" action does not perform a clean unmount — use the tray or CLI instead. --profileimplies 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:FastFileSystemfrom Workbench (tested with 3.2), which wins when present - CDFileSystem via
L:CDFileSystemfrom 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:
- The driver in the RDB for the partition's exact DOS type. If that driver is
damaged, AmiFUSE stops and asks for
--driverinstead 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. FastFileSystemin your drivers folder (%LOCALAPPDATA%\amifuse\driverson Windows,~/.local/share/amifuse/driverselsewhere), for DOS0-DOS7. Place the one from AmigaOS 3.2 there to use it instead of the bundled one.- 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
.infofiles are displayed in Finder - Supports Traditional, NewIcons, and GlowIcons formats
- The
.infofiles 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
.hdfor.adffile 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
--writefor read-write access. Writable Windows mounts remain experimental. - macOS and Linux default to daemon mode; use
--interactiveif 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 writefirst copies its source to a temporary file, so a large write needs free space for the whole source in the temporary directory (TMPDIR, elseTEMPorTMP; Windows normally setsTEMP) as well as room in the image. If it runs short, the write stops with "cannot copy the source to a temporary file" (HANDLER_ERRORwith--json) before the image is touched. A temporary directory on tmpfs, as/tmpoften is, also holds the copy in RAM. SettingTMPDIRto 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.