Skip to main content

This is the final release of amitools-amifuse. The package was a temporary fork of amitools that carried changes AmiFUSE needed before upstream had them. amitools 0.9.0 includes them, and AmiFUSE now depends on upstream amitools directly.

Both distributions install the same amitools Python package, so remove the fork before installing upstream:

pip uninstall amitools-amifuse
pip install 'amitools[vamos]>=0.9.0'

amitools - AmigaOS tools for other platforms

PyPI Python Docs Tests

amitools is a set of command line tools and Python libraries for working with classic Amiga disk images, file systems, Kickstart ROMs, icons and executables on macOS, Linux and Windows. Its centrepiece, vamos, runs AmigaOS command line programs directly on the host by emulating the 68k CPU and the AmigaOS API.

The tools target the classic 680x0 Amiga with AmigaOS 1.x to 3.x and are written for developers, so a background in Amiga programming helps.

Installation

amitools supports Python 3.11 through 3.15 and can be installed with pip or uv.

Tools only

pip install amitools

This installs the pure Python package: all tools except vamos work out of the box.

With vamos

vamos needs the 68k CPU emulator from the machine68k package, which the vamos extra pulls in:

pip install 'amitools[vamos]'

machine68k is a C extension published as a source package, so a C compiler has to be available (Xcode command line tools on macOS, gcc on Linux, Visual Studio Build Tools on Windows).

With uv, install the command-line tools in an isolated environment:

uv tool install amitools

To include vamos and its emulator dependency:

uv tool install 'amitools[vamos]'

Latest development version

pip install -U git+https://github.com/cnvogelg/machine68k.git
pip install -U git+https://github.com/cnvogelg/amitools.git

Repeat the commands to update. The development version has the newest features but may be unstable from time to time.

Optional packages

  • lhafile lets the file scanners look inside .lha archives.
  • pypng is needed by icontool to import and export PNG images.

Tools

Tool Purpose Docs
xdftool Create, inspect and modify ADF and HDF disk images: format, list, read, write, delete, pack and unpack whole images, boot blocks, bitmaps xdftool
xdfscan Scan single images or whole directory trees of ADF/HDF files and verify their file systems xdfscan
rdbtool Create and edit hard disk images and devices with a Rigid Disk Block: partitions, file system drivers, geometry rdbtool
romtool Scan, split, patch and build Kickstart ROM images for emulators, soft kickers and flash ROMs romtool
icontool List and batch edit Workbench .info icon files: tool types, positions, structure fields, PNG import and export icontool
vamos Run AmigaOS command line programs on the host: the Virtual Amiga OS vamos, reference, libraries
vamospath Convert between AmigaOS and host paths using a vamos configuration
vamostool Helpers around vamos: path conversion, type inspection, library profile dumps and state file info
hunktool Load and dump Amiga Hunk executables, libraries, object files and overlays
typetool Inspect the AmigaOS C structure definitions vamos uses
fdtool Read Commodore's .fd function description files and dump them in several formats, including vamos' code structures
geotool Detect and compute disk geometries (cylinders, heads, sectors) for image files and sizes

Every tool prints its usage with -h or help.

Quick examples

# list a floppy image, then read a file from it to the current directory
xdftool wb310.adf list
xdftool wb310.adf read c/dir

# create a new disk, format it and copy a file in, all in one command line
xdftool test.adf format "My Image" + makedir c + write myfile c

# create a 10 MiB RDB hard disk image with one partition
rdbtool work.hdf create size=10Mi + init + fill

# check a whole directory tree of disk images
xdfscan my_disks

# show what is inside a Kickstart ROM
romtool scan kick31.rom -i

# run an Amiga program; -V maps a host directory to an Amiga volume
vamos -V work:/path/to/dir myprog

Python libraries

The tools are built on packages you can use in your own code:

Package Contents
amitools.fs OFS and FFS file systems, block devices and image files, Rigid Disk Blocks and partitions
amitools.binfmt Readers for Amiga Hunk binaries (binfmt.hunk) and the ELF subset used by AROS m68k (binfmt.elf), with relocation
amitools.rom Kickstart ROM parsing, splitting and building
amitools.icon Workbench .info icon files
amitools.fd Parser for .fd function description files
amitools.scan Scanners that walk file trees, .lha archives and disk images
amitools.vamos The vamos runtime: machine, memory, scheduler, library and device implementations

The vamos library API is described in the library documentation.

Development

Clone the repository and set up an editable install with the development and test requirements:

git clone https://github.com/cnvogelg/amitools.git
cd amitools
make init

make init installs machine68k from its git repository, the test and documentation tools, and amitools itself in editable mode, so edits in the tree take effect immediately.

To set up the same environment with uv, create and activate a virtual environment, then install the existing development and test requirements:

uv venv
# macOS/Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate
uv pip install -r requirements-dev.txt -r requirements-test.txt -e .

Tests

The unit tests run in a few seconds:

pytest test/unit

pytest test also runs the vamos test suite, which executes the prebuilt Amiga test programs under vamos and compares their output with recordings from real Amigas; add --full-suite for the slow tests as well. make test runs everything through tox for all supported Python versions. Rebuilding the test programs needs the cross compilers described in test/README.md.

Publishing releases

The Build and publish Python distributions workflow builds a source archive and a pure Python wheel, checks their metadata, runs the test suite, and smoke-tests the installed command line tools. Pull requests and manual runs retain the packages as workflow artifacts without publishing them.

To enable publishing, create the pypi and testpypi environments in the GitHub repository. Configure a trusted publisher for the amitools project on each index using owner cnvogelg, repository amitools, workflow publish-to-pypi.yml, and the matching environment name. PyPI and TestPyPI require separate publisher registrations; no API tokens are needed. See the PyPA setup guide for registration details.

After setup, pushes to upstream main publish development builds to TestPyPI. Pushing a v* release tag publishes the source archive and wheel to both PyPI and TestPyPI after the build and tests pass. The two uploads are independent, so a TestPyPI outage does not block a PyPI release. Publishing is disabled in forks.

Versions come from Git tags via setuptools-scm. Development builds omit the local Git hash suffix so package indexes accept them. TestPyPI skips files that are already present, allowing a workflow to be rerun. PyPI releases require a new version if that version has already been uploaded.

Code style and docs

The code is formatted with Ruff: make format. The documentation is Sphinx; make docs builds it into build/docs/html.

Contributing

Bug reports and pull requests are welcome on GitHub. Please add a unit test for a fix where possible and run ruff format . before submitting.

License and authors

amitools is written by Christian Vogelgsang chris@vogelgsang.org, with contributions from many others, and is licensed under the GNU General Public License version 2 or later.

Metadata

Release files for amitools-amifuse 0.9.0.post1

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

Source distribution (sdist)

Source distribution for amitools-amifuse 0.9.0.post1
File Size Uploaded Provenance Actions
amitools_amifuse-0.9.0.post1.tar.gz 3.8 MB With provenance Details for amitools_amifuse-0.9.0.post1.tar.gz

Built distribution (wheel)

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

Total release size: 4.6 MB

Release files / amitools_amifuse-0.9.0.post1.tar.gz

Download URL amitools_amifuse-0.9.0.post1.tar.gz
Size 3.8 MB
Tags Source
SHA-256 checksum
How to use checksums
364bc58678e85ee6c1d873f5a4b9d8a5938501d28caf3c98d0a192526618fc3f
BLAKE2b-256 checksum
How to use checksums
893144d935bbf4b9c7eb5fdd58479b7d84eb8c18118863fad0783b836e6152bf
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 14, 2026.

Transparency log

Release files / amitools_amifuse-0.9.0.post1-py3-none-any.whl

Download URL amitools_amifuse-0.9.0.post1-py3-none-any.whl
Size 820.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4ea2d91e4a4daacacd6d3afbb4a9ea5da13d30f143354dbefd207286cfe2f36a
BLAKE2b-256 checksum
How to use checksums
6d41a7a8c1340b3c44bae2e52b80a6273a83ca80875324340b1baaacfb4643d0
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 14, 2026.

Transparency log

Security for amitools-amifuse 0.9.0.post1

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 amitools_amifuse-0.9.0.post1.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 14, 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