Skip to content

Installation

Jump to bottom
Julien Clauzel edited this page Jul 3, 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? On Windows, download the latest ZX-Next-Unite-v8.x executable from the Releases page and run it — no Python needed. Everything below is for running from source or on Linux/macOS.

Contents

Choosing an install method

You are on… Recommended method
Windows, just want to run it Option A — download the executable
Windows and want the latest/dev version, or to tinker Option B — from source
Linux / macOS Option B — from source (there is no pre-built binary)

Option A — Windows executable (easiest)

  1. Go to the Releases page.
  2. Download the latest ZX-Next-Unite-v8.x executable.
  3. (Optional) Also download the .sync4 dot command if you want to use NextSync with a real Spectrum Next.
  4. Run the executable. No Python or extra libraries required.

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.9 or newer — Python 3.13 is recommended (it is what the app is developed and tested against). 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

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

To update later:

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

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.

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).

All three 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).

  • Windows: if hdfmonkey is missing, the app shows an error in the log and a Download and install button (bottom-right). Clicking it fetches and unzips hdfmonkey_windows.zip into the app's folder automatically. If that download is blocked (firewall / no internet), download it on another machine and copy hdfmonkey.exe next to the app.
  • Linux / macOS: install it manually following the instructions at github.com/gasman/hdfmonkey.

MAME emulator

For the app to detect MAME, add it to your OS PATH. Installation and configuration are documented at wiki.specnext.dev/MAME:Installing.

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 .sync4 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: .sync4 — 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:

    .sync4 -send <file|directory>        # push from Next → PC
.sync4 -send myFile.nex -fast        # with a speed hint

    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 .sync4 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 .sync4 <new-ip>.
  5. Click Yes, start NextSync server on the PC, then run .sync4 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 .sync4 source lives under nextsync/sync in this repo and requires SDCC 4.5.0. On Windows, build it with nextsync/sync/build.ps1. A command-line server (nextsync4.py, under nextsync/sync/server) is also available and supports -send and Ctrl-C.

Troubleshooting

  • hdfmonkey missing on Windows and auto-download fails. This is almost always a firewall blocking outbound calls from python.exe (or the app exe). Either allow it temporarily in Windows Defender Firewall, or download hdfmonkey_windows.zip on another machine and copy hdfmonkey.exe next to the app (the safer option).
  • hdfmonkey on Linux/macOS. There is no auto-download; install it manually 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:

ZX-Next-Unite

User Manual

Tools

Online libraries

The rest

Clone this wiki locally