How to build an mac os app from a python script having a PySide2 GUI?


  • works with Python 3.8.5
  • macOS 10.15.7 Catalina
  • uses PySide2 and py2app


  • PySide2 must be added under OPTIONS to the packages list
  • when running the app then still an error occurs: Library not loaded: @rpath/libshiboken2.abi3.5.15.dylib, Reason: image not found


The slightly modified could look like this:

from setuptools import setup

APP = ['']
    'packages': ['PySide2'],
    'iconfile': 'some_icon.icns',
    'plist': {
        'CFBundleDevelopmentRegion': 'English',
        'CFBundleIdentifier': "",
        'CFBundleVersion': "1.0.0",
        'NSHumanReadableCopyright': u"Copyright © 2020, Serge Ballesta, All Rights Reserved"

    options={'py2app': OPTIONS},

Additionally, an icon definition and a few plist entries for some basic information have been added.

The whole build is best triggered with a script that could look like this:

python3 -m venv venv
. venv/bin/activate
pip install PySide2
pip install py2app
python py2app      
cp ./venv/lib/python3.8/site-packages/shiboken2/libshiboken2.abi3.5.15.dylib ./dist/


Here the screenshot of a test run:


I think what you're missing is the inclusion of the Python3 Framework in your application bundle. I've developed a simple macOS app myself recently, however I wanted to have a little more insight on how to do so, so I did a bit of digging into the actual structure of an application. Basically, you are going to put everything into a normal folder with the name of your application. Call this folder MyApp. Inside this folder we'll have another called Contents. From my understanding, py2app just takes all of the things that make up your app, and structures them inside of this folder as well as creates an Info.plist file, which also goes inside of Contents. So far, here is what you have:


-> Contents

-> -> Info.plist

In addition to the Info.plist file with all of the necessary properties, in your Contents folder you will have a MacOS folder and a Resources folder at minimum. Your issue is that you also need a Frameworks folder, where you would add the required version of Python.

Now, your app hierarchy should look like:


-> Contents

-> -> Info.plist

-> -> MacOS

-> -> Resources

-> -> Frameworks

In the Frameworks folder, you can put the full Python 3 framework you're working with to build the app, as well as any site-packages that you require to run the application, and then you can reflect all of those changes in the executable so that you are pointing to the correct installations.

To my understanding, all that's necessary to make the application functional on MacOS is to ensure that your main executable is placed in the MacOS folder and points to the Python located in your Frameworks folder, your icon .icns file is placed in the Resources folder, and your Info.plist file is built.

In order for MacOS to recognize it as a full application, I believe you possibly need to use productbuild and include a Developer license certificate, but it's really only necessary if you want the application to be distributed. Otherwise, I just added the extension .app to MyApp, which converts it into an application.

Without the above-mentioned license/certificate whatever, it probably won't recognize that it should find your icon file and add it, so if you open it in Preview, select-all, and copy it, you should be able to right-click on the application, press 'Get Info', and paste the icon on top of the current icon in the window to make it display correctly.

EDIT: My resources for learning about making macOS apps:

Bundle structure

Including frameworks

Signing your application

productbuild manpage

If you want to package for OSX, you should either

Create a Brew Tap

This probably makes the most sense for an open source developer

General Instructions

  • host your code in git (does not need to be GitHub)
  • create a Formula (Formula Cookbook)
  • fork homebrew-core on GitHub
  • add your Formula and create a pull request to get it into the main repo
  • support your pull request such that it is completed

Join the Apple Developer Program

This probably makes the most sense for a closed source developer


This program costs 99USD annually, but will allow you to sign your package/final binary and distribute it yourself or on their App Store

After creating your account, here's a guide for packaging and signing for OSX

  • structure your code to support signing (add a build step to copy your work into a clean path to avoid frustrating rework)
  • % codesign -s <Developer ID Application signing identity> /path/to/code
  • pick a storage format (.zip, .dmg, .pkg) and bundle your application as it