Skip to content

Installation

Jump to bottom
Julien Clauzel edited this page Jul 28, 2026 · 19 revisions

Installation

ZX-Next-Unite is a cross-platform (Windows, Linux, macOS) desktop app written in Python on top of Qt 6 (PySide6). This page covers everything you need to get it running, plus the optional emulators and tools it works with.

In a hurry? Download the package for your platform from the Releases page — the Windows .exe, the Linux x86_64 .tar.gz or the macOS (Apple Silicon) .zip — and run it, no Python needed. Everything below is for running from source or for the optional emulators and tools.

Contents

Choosing an install method

You are on… Recommended method
Windows, just want to run it Option A — download the package
Linux (x86_64) or macOS (Apple Silicon), just want to run it Option A — download the package (since v9.1.9)
Any platform, want the latest/dev version or to tinker Option B — from source
Any platform with Python 3.10+, prefer a package manager Option C — pipx
Linux / macOS on another architecture (e.g. Intel Mac, ARM Linux) Option C — pipx or Option B — from source

Option A — Pre-built packages (easiest)

Since v9.1.9 every release carries a package per platform, built by CI from the tagged source:

  1. Go to the Releases page.
  2. Download and run the package for your platform:
    • Windows — zx-next-unite-v9.x.x.exe: just run it.
    • Linux (x86_64) — zx-next-unite-v9.x.x-linux-x86_64.tar.gz: extract with tar xzf and run the binary inside (the executable bit is preserved by the tarball).
    • macOS (Apple Silicon) — zx-next-unite-v9.x.x-macos-arm64.zip: extract and start the app. It is not code-signed, so the first launch needs right-click → Open in Finder (or xattr -cr on the .app) to get past Gatekeeper.
  3. (Optional) Also download the sync5 dot command if you want to use NextSync with a real Spectrum Next.
  4. No Python or extra libraries required — and the app's built-in update check offers you each new release with the right package for your platform.

You can still add the optional emulators/tools described in Optional components later.

Option B — Install from source (Windows, Linux, macOS)

1. Prerequisites

  • Python 3.10 or newer — the floor the CI test suite runs on (it also tests 3.13, which is what the release binaries bundle). The stock Python of Ubuntu 22.04 / Debian 12 and later works out of the box. Otherwise download from python.org/downloads. On Windows, tick "Add python.exe to PATH" in the installer.
  • git (or download the source as a ZIP from GitHub).

2. Get the code

git clone https://github.com/jclauzel/ZX-Next-Unite
cd ZX-Next-Unite

3. Create a virtual environment (recommended)

A virtual environment keeps these dependencies out of your system Python. It is optional but recommended — and much safer than installing into system Python.

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Linux / macOS:

python3 -m venv .venv
source .venv/bin/activate

4. Install the dependencies

Using the requirements file (installs PySide6 plus the optional extras):

python -m pip install -r REQUIREMENTS.txt

…or install them explicitly:

python -m pip install PySide6 pygame-ce itch-dl flask send2trash

Only PySide6 is strictly required; pygame-ce, itch-dl, flask and send2trash are optional (see Dependencies explained).

To update later:

python -m pip install --upgrade PySide6 pygame-ce itch-dl flask send2trash

5. Run it

python zx-next-unite.py

On Linux/macOS use python3 zx-next-unite.py.

Note: the script name is lower-case zx-next-unite.py. This matters on Linux and macOS, where filenames are case-sensitive.

Linux / macOS extra step

CSpect is a .NET application, so to launch it you also need Mono — see Mono below. You do not need Mono if you only use MAME or don't use an emulator at all.

Option C — pipx (from PyPI)

Since v9.1.9 the app is on PyPI, so with Python 3.10+ and pipx installed it is one line on any platform:

pipx install "zx-next-unite[full]"

This installs the zx-next-unite command (and nextsync5, the standalone command-line NextSync server) into an isolated environment that pipx upgrade zx-next-unite keeps up to date. Drop [full] for a minimal install without the optional extras (retro pygame views, the itch.io tab, Recycle-Bin deletes, the NextSync HTTP bridge).

Compared to Option B this needs no git checkout and cannot conflict with other Python software on your system. The optional emulators/tools work the same way — see Optional components.

Dependencies explained

Package Required? What it enables
PySide6 Required The Qt 6 GUI toolkit the whole app is built on.
pygame-ce Optional The retro 8-bit log windows and the "Alien Floyd's" animated background/tab. The app runs fine without it.
itch-dl Optional The itch.io tab (browse/install your itch.io collections). The tab only appears when this package is installed. Provided by itch-dl (MIT).
flask Optional The NextSync HTTP bridge — the web server that lets a Next drive another Next's SD card via the .http dot command. Its Settings toggle is greyed out until this package is installed. Provided by Flask by the Pallets team (BSD-3-Clause).
send2trash Optional The "Send deleted files to the Recycle Bin" option — files deleted in the local file explorers go to the system Recycle Bin / Trash instead of being removed permanently. Its Settings toggle is greyed out until this package is installed. Provided by Send2Trash by Andrew Senetar and contributors (originally Virgil Dupras, BSD).

All five are installed by pip install -r REQUIREMENTS.txt.

Optional components

None of these are needed to start the app, but they unlock the emulator and disk-image features.

CSpect emulator

CSpect by Mike Dailly is the recommended emulator. There are two ways to set it up:

  • Automatic (recommended): if you own CSpect on itch.io, enter your itch.io API key in the app, open the itch.io tab, select CSpect and click Install. Because CSpect ships with hdfmonkey for every platform, this leaves you fully set up — no separate hdfmonkey install needed.
  • Manual: download CSpect and either extract it into the app's folder or make sure it is reachable via your OS PATH. Download from mdf200.itch.io/cspect or cspect.org.

Required ROMs: the two Spectrum Next ROM files enNextZX.rom and enNxtMMC.rom must be placed in the root folder of CSpect. They are normally included in the CSpect download.

For sound/music playback on Windows you also need OpenAL.

On Linux/macOS you additionally need Mono.

hdfmonkey

hdfmonkey (by Matt Westcott) is the external tool used for all HDF disk-image operations. You only need to install it separately if you did not install CSpect via itch.io (that package already bundles it).

  • If hdfmonkey is missing, the app shows an error in the log and a Download and install HDF Monkey button (bottom-right). Clicking it fetches the pre-compiled build from the specnext.com forum and unpacks the binary for your platform — Windows, Linux and macOS (Intel and Apple Silicon) — into the app's downloads/hdfmonkey/ folder automatically.
  • If that download is blocked (firewall / no internet), download it on another machine and copy the binary next to the app, or build it from source following github.com/gasman/hdfmonkey.

MAME emulator

MAME is the alternative emulator. Mainline MAME includes ZX Spectrum Next support (the tbblue machine and the various specnext_ks* kickstart variants), so a current MAME build can boot your Next image directly. The Spectrum Next side of MAME is documented on the official Spectrum Next wiki: wiki.specnext.dev/MAME:Installing.

How the app finds MAME

At startup ZX-Next-Unite looks for a MAME executable in two places and uses the first hit:

  • a build inside the app's own downloads/mame folder, and
  • whatever mame is on your OS PATH.

On Linux/macOS downloads/mame is checked first (so a build you drop there is preferred over an older mame from your distro/PATH). On Windows the order is reversed — PATH first, then downloads/mame.

When MAME is found, the SD Card tab shows a 🕹 Launch Mame button and the MAME options group. When it isn't found, Windows shows an ⬇ Install MAME button in its place (see below); Linux/macOS simply hide the group until a MAME is available.

Windows — automatic install

If MAME isn't found on a 64-bit Windows PC, click ⬇ Install MAME on the SD Card tab. The app fetches the latest official MAME release for your CPU (x64 / arm64) from the mamedev/mame GitHub releases and unpacks it into downloads/mame — no 7-Zip or other tools required. Progress is shown in the SD Card log window, and the Launch button appears as soon as it finishes (no restart needed).

A startup update check — Settings → "Check for a newer MAME version at startup" (on by default) — offers to update your app-installed MAME when a newer release is published.

Linux / macOS — install it yourself

MAME publishes no official pre-built binary for Linux or macOS (the GitHub release only carries Windows binaries), so the app does not auto-install MAME there — it only detects one you provide. Install MAME with:

  • Linux: your distribution's package manager (e.g. sudo apt install mame), or Flatpak from Flathub — see Launching MAME via Flatpak below.
  • macOS: brew install mame (Homebrew), the SDLMAME builds at sdlmame.lngn.net, or build from source.

Tip: you can also drop a self-built or downloaded MAME into the app's downloads/mame folder — on Linux/macOS it is preferred over an older mame on your PATH.

The Spectrum Next boot ROM (required)

MAME needs the Spectrum Next boot ROM to start the machine — without it MAME aborts with a "required files are missing" error. Download tbblue.zip from the NexCreator bootroms folder and place it in MAME's roms folder:

  • an app-installed Windows build: downloads/mame/roms/
  • a Flatpak launch: the Flatpak rom path you set (see below)
  • any other build: its own roms directory (or a folder you pass with -rompath)

Do not extract tbblue.zip. MAME looks for the zip file itself when the tbblue machine is selected. Use only a legally obtained ROM.

Choosing the system and launch options

  • Settings → MAME lets you pick the ROM / system (tbblue, specnext_ks1, specnext_ks2, specnext_ks3) and edit the default MAME launch parameters.
  • The MAME group on the SD Card tab has per-launch options — aspect ratio, sound, mouse, joystick, and an ESC-key toggle (passes -confirm_quit). At launch the app runs MAME as mame <system> <your parameters + these options> -hard1 <your image>, so the loaded disk image is always the last argument.

Launching MAME via Flatpak (Linux)

On Linux the easiest way to get a current MAME is Flathub. ZX-Next-Unite can launch that sandboxed build directly.

  1. Install MAME from Flathub:

    flatpak install flathub org.mamedev.MAME

  2. Put the boot ROM where MAME can read it. Create a roms folder in your home directory and drop tbblue.zip (unextracted) into it:

    mkdir -p ~/roms   # then copy tbblue.zip into ~/roms

  3. Enable it in the app. Open Settings → MAME, tick Launch Mame with Flatpak, and set Flatpak rom path to the folder from step 2 (it defaults to ~/roms). All settings are saved to hdfg.cfg.

  4. Every Launch Mame button — on the SD Card tab and in the online-library item viewers (GetIt, ZXDB, zxArt, Unite!, itch.io) — now reads Launch Mame (flatpak) and starts MAME as:

    flatpak run org.mamedev.MAME <system> <your parameters + options> -rompath <your rom path> -hard1 <your image>

    No locally installed MAME binary is needed in this mode.

Flatpak sandboxing. The Flatpak MAME runs sandboxed, so it can only read files in the directories it has been granted. Your rom path and the disk image must be readable inside the sandbox. Paths under your home directory usually work out of the box; for anything elsewhere, grant access with Flatseal or, e.g.:

flatpak override --user --filesystem=/path/to/your/images org.mamedev.MAME

Spectrum Next system images (HDF)

You need a Spectrum Next system image (an .hdf file — think of it as an ISO that contains everything the machine needs to boot). Download one from zxnext.uk/hosted, for example cspect-next-2gb.zip.

OpenAL (sound, Windows)

For CSpect audio on Windows, install the OpenAL runtime from openal.org.

Mono (.NET runtime — Linux/macOS only)

CSpect is written for .NET, so on Linux/macOS you need Mono to run it:

  • Debian / Ubuntu: sudo apt install mono-complete
  • macOS: install the Mono package from mono-project.com (or brew install mono).

See also the Spectrum Next Linux setup guide: wiki.specnext.dev/Development_Tools:Linux_setup.

NextSync — the .sync5 dot command

NextSync lets you push files over Wi-Fi from your PC to a real Spectrum Next (a Kickstarter machine or clone with an ESP Wi-Fi module). ZX-Next-Unite implements the server side; your Next runs a dot command that connects to it over TCP port 2048.

  • Current command: .sync5 — grab it from the Releases page. It adds the Sync4 protocol: faster transfers and the ability to send files back from the Next to the PC:

    .sync5 -send <file|directory>        # push from Next → PC
.sync5 -send myFile.nex -fast        # with a speed hint
.sync5 -listen                       # remote file server (short alias: -l)

    Speed hints: -slow, -default, -fast (no separate syncfast / syncslow commands needed).

  • Legacy command: .sync — the older PC → Next-only dot command still works, so nothing breaks if you keep using it. Backward compatibility is provided by the Sync3 protocol.

Setting it up

  1. Copy the .sync5 dot file into the /dot folder on the root of your Spectrum Next SD card and reboot the Next.
  2. Make sure Wi-Fi is fully set up and that your Next and the PC running ZX-Next-Unite are on the same network, with no firewall blocking inbound TCP 2048 on the PC.
  3. In ZX-Next-Unite, open the NextSync tab, select the root folder you want to sync, and click Start NextSync server. Tip: for the first run, enable Sync once so the server stops after a single sync while you verify things.
  4. The log window shows this machine's IP address(es). The first time you run the command on the Next it will ask which IP to connect to — enter that address. (On Linux/macOS run ifconfig / ip addr if you need to list all IPs.) The Next stores this in C:/sys/config/nextsync.cfg; change it later by editing that file or running .sync5 <new-ip>.
  5. Click Yes, start NextSync server on the PC, then run .sync5 on the Next. Your Next connects and the files transfer.

The usual syncignore.txt / syncpoint.dat logic applies for controlling what gets synced — see Jari Komppa's original documentation.

Building the dot from source

The .sync5 source lives under nextsync/sync in this repo. There are two ways to build it, from the same nextsync.c / gfx.c protocol code:

1. Classic build (SDCC). The original build. Requires SDCC 4.5.0; on Windows run nextsync/sync/build.ps1. This produces a standard esxDOS/NextZXOS dot command, which loads at $2000 and must fit the 8 KB limit ($2000–$3FFF). The command has grown to sit right against that ceiling.

2. dotN build (z88dk) — removes the 8 KB limit. Under nextsync/sync/z88dk/ is a parallel build of the same command as a "dotN" command, which is not bound by the 8 KB limit: appmake splits it into the 8 KB page at $2000 plus overflow pages that the dotN loader allocates from NextZXOS and maps into extra banks at run time. Requires z88dk (e.g. installed at C:\z88dk); on Windows run nextsync/sync/z88dk/build_dotn.ps1. The SDCC build is kept as the known-good fallback. See nextsync/sync/z88dk/README.md for the memory model and build details.

The .sync5 -listen remote file explorer (Home → Remote file explorer; the short alias .sync5 -l does exactly the same thing) is provided by this z88dk dotN build — it needs the extra room the dotN gives, so it is not available in the classic SDCC build. Press BREAK (Caps Shift + Space) on the Next to end a -listen session cleanly; it always waits for any in-progress transfer to finish first, so no file or directory is corrupted.

A command-line server (nextsync5.py, under nextsync/sync/server) is also available and supports -send and Ctrl-C.

Building the standalone executable

The pre-built packages offered in Option A are produced with PyInstaller by the release workflow (.github/workflows/release.yml), which builds all three platforms from the tagged source on every release. You only need PyInstaller if you want to build a package yourself; running from source (Option B) never requires it.

Install PyInstaller into the same environment as the app:

python -m pip install pyinstaller

Then build (this is the same command CI runs):

pyinstaller --clean --onefile --windowed --noupx --collect-all itch_dl --collect-all bs4 zx-next-unite.py
  • --onefile — a single self-contained executable.
  • --windowed — no console window (GUI app).
  • --noupx — skip UPX compression (a smaller download is not worth the antivirus false positives UPX-packed executables tend to trigger; drop the flag and add --upx-dir <folder> with UPX if you prefer a smaller personal build).
  • --collect-all itch_dl --collect-all bs4 — fully bundle itch-dl and its dependency Beautiful Soup so the optional itch.io feature works in the frozen build (a bare import itch_dl does not pull in its submodules).

The result is dist/zx-next-unite.exe (Windows), dist/zx-next-unite (Linux) or dist/zx-next-unite.app (macOS).

Tip — always add --clean when rebuilding after updating the code. PyInstaller's incremental build cache can otherwise mix a freshly analysed module with a stale cached copy of another, producing a confusing ImportError: cannot import name … from … at startup even though the source is correct. pyinstaller --clean … wipes the cache first and avoids it.

  • hdfmonkey missing and the auto-download fails. This is almost always a firewall blocking outbound calls from python.exe (or the app executable). Either allow it temporarily (e.g. in Windows Defender Firewall), or fetch hdfmonkey on another machine and copy the binary next to the app — on Windows hdfmonkey_windows.zip, on Linux/macOS build it from github.com/gasman/hdfmonkey.
  • App won't start / import errors. Confirm PySide6 installed into the same Python you're launching with (activate your venv first). A recent Python 3 is required — see Prerequisites.
  • CSpect won't launch on Linux/macOS. You need Mono — see Mono.
  • Filenames with special characters (e.g. single quotes) on the Next image may not download correctly.
  • ESP / Wi-Fi transfer errors during NextSync. If your connection is unstable, reduce the transfer speed (the Slow transfer option, or -slow).
  • Timer messages in the console during NextSync can be safely ignored.
  • Still stuck with NextSync? Try Jari Komppa's original command-line nextsync.py first — if that syncs, ZX-Next-Unite should too, since it shares the same code base. His setup guide is in nextsync.txt inside the nextsync v1.2 release.

Resetting settings: all options are stored in a single hdfg.cfg file created next to the app. To reset everything, back up and delete that file.

Supporting the tools this builds on

ZX-Next-Unite stands on the shoulders of others' work — please consider supporting them:

The pre-built packages are produced with this build-time tool (needed only to package the standalone executables, not to run ZX-Next-Unite from source):

ZX-Next-Unite

User Manual

Tools

Online libraries

The rest

Clone this wiki locally