Skip to content

Developers

NOTE: It is HIGHLY RECOMMENDED to use a Python virtual environment (venv). The package dependencies are tightly pinned and newer versions may not produce a correct executable when built with PyInstaller.

Requirements

  • Python 3.10–3.13 for your operating system (3.14+ is not yet supported)
  • A terminal / development shell
  • git installed and working

Setup

Clone the repository and run the dev setup:

git clone https://github.com/whatsnowplaying/whats-now-playing.git
cd whats-now-playing
./builder.sh dev

If your system default Python is unsupported (e.g. 3.14+) or you have multiple versions installed and need to target a specific supported one, set PYTHONBIN before running the script:

PYTHONBIN=/usr/local/bin/python3.11 ./builder.sh dev

builder.sh defaults to python3 (or python on Windows) found on PATH. PYTHONBIN overrides that for both the venv creation and all subsequent build steps.

This creates a venv/ directory in the source tree, installs all dependencies (including dev and test extras), syncs vendored libraries, writes version info, sets up NLTK data, compiles templates, and compiles Qt resources.

Re-running ./builder.sh dev after pulling updates will refresh all of the above without recreating the venv from scratch.

Running from Source

Activate the venv and launch:

source venv/bin/activate        # Windows: venv\Scripts\activate
./wnppyi.py

Running Tests

pytest

See CLAUDE.md for more detail on the test suite layout and code quality tools.

Build Executable

To build a stand-alone executable:

./builder.sh           # auto-detects platform (macOS or Windows)
./builder.sh macosx    # explicit macOS build
./builder.sh windows   # explicit Windows build
./builder.sh linuxbin  # Linux build via Docker (see below)

The script handles the full build pipeline and produces a zip file containing the binary in the current directory.

Linux Builds

Linux binaries are built inside a Docker container to ensure compatibility with older glibc versions (Debian Bullseye / glibc 2.31). This produces a binary that runs on Ubuntu 20.04 and later.

Requirements:

  • Docker installed and running
  • docker buildx support (included with Docker Desktop and Docker Engine 19.03+)

Run the build:

./builder.sh linuxbin

This builds the Docker image automatically, runs the full PyInstaller pipeline inside the container, and writes a WhatsNowPlaying-<version>-Linux-<arch>.zip file to the current directory. Output files are owned by the current user.