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
amitoolsPython 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
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.
- Documentation: https://amitools.readthedocs.io/
- Source and issues: https://github.com/cnvogelg/amitools
- Releases: https://pypi.org/project/amitools/, change log
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
.lhaarchives. - pypng is needed by
icontoolto 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 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.