Guide to building sioyek from HEAD on macOS arm64 (2026)

[milan-panta]

The last official macOS release is v2.0.0 from December 2022, but the development branch has had steady commits since then. I got a working build on Apple Silicon and wanted to write up the steps since the existing guides (especially #1031) are either incomplete or out of date.

Tested on: macOS 26.4, Apple Silicon (arm64), Qt 6.11.0 from Homebrew.

---

Prerequisites

xcode-select --install
brew install qt

You do not need qt@5, freeglut, mesa, cmake, or harfbuzz. The build script's comment about those is outdated -- Qt6 on macOS uses Metal and doesn't need any of that. MuPDF bundles its own harfbuzz.

---

Steps

1. Clone with submodules

MuPDF and zlib are both submodules so --recursive is required:

git clone --recursive --branch development --depth=1 \
  https://github.com/ahrm/sioyek ~/sioyek_build
cd ~/sioyek_build

2. Build MuPDF

cd mupdf
make HAVE_GLUT=no -j$(sysctl -n hw.ncpu)
cd ..

3. Configure with Qt6

Patch the macOS deployment target and run qmake:

sed -Ei '' "s/QMAKE_MACOSX_DEPLOYMENT_TARGET.=.[0-9]+/QMAKE_MACOSX_DEPLOYMENT_TARGET = $(sw_vers -productVersion | cut -d. -f1)/" pdf_viewer_build_config.pro

export PATH="/opt/homebrew/opt/qt/bin:$PATH"
qmake "CONFIG+=non_portable" "QMAKE_CXXFLAGS+=-Wno-implicit-function-declaration" pdf_viewer_build_config.pro

The -Wno-implicit-function-declaration flag is necessary with Qt 6.11 on macOS 26. Qt's qyieldcpu.h implicitly calls __yield without declaring it, which Clang treats as an error. This is a Qt bug, not a sioyek bug.

4. Build

make -j$(sysctl -n hw.ncpu)

5. Assemble the app bundle

rm -rf build && mkdir build
mv sioyek.app build/
cp -r pdf_viewer/shaders build/sioyek.app/Contents/MacOS/shaders
cp pdf_viewer/prefs.config build/sioyek.app/Contents/MacOS/prefs.config
cp pdf_viewer/prefs_user.config build/sioyek.app/Contents/MacOS/prefs_user.config
cp pdf_viewer/keys.config build/sioyek.app/Contents/MacOS/keys.config
cp pdf_viewer/keys_user.config build/sioyek.app/Contents/MacOS/keys_user.config
cp tutorial.pdf build/sioyek.app/Contents/MacOS/tutorial.pdf

6. Embed PATH into Info.plist

This lets sioyek find shell utilities when launched from the Dock:

INFO_PLIST="build/sioyek.app/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Add :LSEnvironment dict" "$INFO_PLIST" 2>/dev/null || true
/usr/libexec/PlistBuddy -c "Add :LSEnvironment:PATH string $PATH" "$INFO_PLIST" 2>/dev/null || \
/usr/libexec/PlistBuddy -c "Set :LSEnvironment:PATH $PATH" "$INFO_PLIST"

7. Bundle Qt frameworks

macdeployqt build/sioyek.app

You will see a few "Cannot resolve rpath" warnings for QtPdf and QtVirtualKeyboard. These are optional Qt modules that sioyek doesn't use and can be ignored.

8. Codesign and install

codesign --force --sign - --deep build/sioyek.app
cp -r build/sioyek.app /Applications/sioyek.app

---

Result

The resulting app is fully self-contained (around 135 MB with all Qt frameworks bundled) and passes codesign verification.

---

Summary

xcode-select --install
brew install qt

git clone --recursive --branch development --depth=1 \
  https://github.com/ahrm/sioyek ~/sioyek_build
cd ~/sioyek_build

cd mupdf && make HAVE_GLUT=no -j$(sysctl -n hw.ncpu) && cd ..

sed -Ei '' "s/QMAKE_MACOSX_DEPLOYMENT_TARGET.=.[0-9]+/QMAKE_MACOSX_DEPLOYMENT_TARGET = $(sw_vers -productVersion | cut -d. -f1)/" pdf_viewer_build_config.pro

export PATH="/opt/homebrew/opt/qt/bin:$PATH"
qmake "CONFIG+=non_portable" "QMAKE_CXXFLAGS+=-Wno-implicit-function-declaration" pdf_viewer_build_config.pro

make -j$(sysctl -n hw.ncpu)

rm -rf build && mkdir build
mv sioyek.app build/
cp -r pdf_viewer/shaders build/sioyek.app/Contents/MacOS/shaders
cp pdf_viewer/prefs.config build/sioyek.app/Contents/MacOS/prefs.config
cp pdf_viewer/prefs_user.config build/sioyek.app/Contents/MacOS/prefs_user.config
cp pdf_viewer/keys.config build/sioyek.app/Contents/MacOS/keys.config
cp pdf_viewer/keys_user.config build/sioyek.app/Contents/MacOS/keys_user.config
cp tutorial.pdf build/sioyek.app/Contents/MacOS/tutorial.pdf

INFO_PLIST="build/sioyek.app/Contents/Info.plist"
/usr/libexec/PlistBuddy -c "Add :LSEnvironment dict" "$INFO_PLIST" 2>/dev/null || true
/usr/libexec/PlistBuddy -c "Add :LSEnvironment:PATH string $PATH" "$INFO_PLIST" 2>/dev/null || \
/usr/libexec/PlistBuddy -c "Set :LSEnvironment:PATH $PATH" "$INFO_PLIST"

macdeployqt build/sioyek.app
codesign --force --sign - --deep build/sioyek.app
cp -r build/sioyek.app /Applications/sioyek.app

[GabeYaw]

Thanks for this! I just found this app and couldn't work out how to install a recent version

[Zhou-Xuanyu]

If need to run sioyek from command line and pass parameter, put something like the following into /usr/local/bin/sioyek or any where in the PATH can redirect

#!/bin/sh
exec /Applications/sioyek.app/Contents/MacOS/sioyek "$@"