Recommended way to install PyQt5 with fbs on macOS

If you've been trying to set up fbs (fman build system) on macOS with PyQt5, you may have run into a frustrating tangle of version incompatibilities. Homebrew installs the latest versions of Python and PyQt5, but fbs expects older, specific versions. The result is often broken builds, missing dylibs, and a lot of wasted time.

This guide walks through a working combination of Python, PyQt5, PyInstaller, and fbs that has been tested on macOS — including support for QtWebEngine.

The problem

fbs pins older versions of its dependencies, including PyInstaller 3.4 and Python 3.6. If you install Python and PyQt5 through Homebrew, you'll typically end up with newer versions that fbs doesn't support. This causes all kinds of issues when you try to freeze (package) your application, especially if you're using components like QtWebEngine.

Even using a macOS virtual machine won't help here — the issue is with the dependency versions, not the environment.

Install the correct Python version

Start by removing any Homebrew-installed versions of PyQt5 to avoid conflicts:

brew uninstall pyqt5

Then download and install Python 3.6.8 using the official installer from python.org:

Download python-3.6.8-macosx10.9.pkg

Using the official .pkg installer (rather than Homebrew) avoids path and compilation issues that can make packaging on macOS especially painful.

Set up a virtual environment

Once Python 3.6.8 is installed, create a virtual environment for your fbs project:

python3.6 -m venv myproject-env
source myproject-env/bin/activate

This keeps your fbs dependencies isolated from anything else on your system.

Install the dependencies

Create a requirements.txt file with the following contents:

fbs==0.9.0
PyQt5==5.15.1
PyQt5-sip==12.8.1
PyQtWebEngine==5.15.1

If your project uses additional PyQt5 modules, you can include them as well:

PyQt3D==5.15.1
PyQt5-stubs==5.14.2.2
PyQtChart==5.15.1
PyQtDataVisualization==5.15.1
PyQtPurchasing==5.15.1

Install the requirements:

pip install -r requirements.txt

Override PyInstaller

Here's the part that makes everything work. fbs pins PyInstaller 3.4, but that version has issues on macOS with the Python and PyQt5 versions above. PyInstaller 3.6 doesn't work either. The version that does work is PyInstaller 4.0, along with its hooks package.

Force-install them after the other dependencies:

pip install pyinstaller==4.0 pyinstaller-hooks-contrib==2020.9

This overrides the version that fbs installed and brings in fixes for macOS-specific issues, including missing dylibs and QtWebEngine packaging problems.

The winning combination

To summarize, here's the combination that works:

Freezing your app

With everything installed, you can freeze your fbs project as usual:

fbs freeze

After freezing, you may need to manually copy some application resources from your resources folder into the target/<YourApp>.app/Contents/MacOS/ folder. This is a minor manual step, but it's straightforward — just check that any files your app loads at runtime are present in the output directory.

Conclusion

Setting up fbs on macOS requires getting a very specific set of versions lined up. Ince you have the right combination in place, everything works smoothly - including QtWebEngine and other PyQt5 extras. For a more robust setup you may want to consider using PyInstaller directly.