macOS Development Build
The easiest way to test OpenLP is to use the Development Build. Note however that this development release could be a few days or weeks behind the current development trunk.
If you want to run the most up to date version, the following steps will guide you through the process:
Install Dependencies with MacPorts
In order to run the very latest "trunk" (where approved code is updated before release) or developers' personal branches, you will need to install several pieces of extra software. macOS comes with Python pre-installed, but unfortunately it does not have all the required modules. The recommended way to set up the installation is using macports, a free software repository which lets you install different versions of many standard *NIX programs & libraries.
Download and install Xcode from the App Store (it's free). There's more information about Xcode at developer.apple.com.
Xcode contains gcc or clang (C/C++ compiler) and other development tools necessary to set up the testing environment via MacPorts.
Download and install MacPorts from http://www.macports.org/
Tools from Macports in PATH
When you install Macports, it should make itself accessible from the terminal. However, if you choose not to let it do that when you install it, you can do it manually:
We need to modify the environment variable $PATH.
/Users/USERNAME/.profile in a text editor and add the following lines at the end of the file:
# Adding an appropriate PATH variable for use with MacPorts. export PATH=/opt/local/bin:$PATH
To have tools from MacPorts available in your currently open terminal run the following command:
Update list of available packages
To be able to install latest version of libraries you usually need to tell MacPorts to update the package list:
sudo port selfupdate
Install Basic Development Tools
Now we are ready to use MacPorts to install Python, dependencies and other tools. If you want to use git, or vim, etc. then you can install them now (if you already have an editor, and/or you want to use the Nightly Build Tarball, then you can skip this):
sudo port -N install git mupdf python39
If you aren't using MacPorts' Python 2.X, you can make Python 3 the default Python:
sudo port select --set python python39
If you want to keep on using Python 2 as your default python, you can set Python 3 only to be your default 'python3':
sudo port select --set python3 python39
Install Python Libraries (MacPorts)
Now you can install libraries. This can take a lot of time (several hours) compiling the Qt5 libraries.
First install PyQt5 with both WebEngine and WebKit (they are called "variants" in MacPorts language).
sudo port -N install py39-pyqt5 py39-pyqt5-webengine
Then install the rest.
sudo port -N install py39-pip py39-lxml py39-sqlalchemy py39-mako py39-pytest py39-beautifulsoup4 \ py39-psycopg2 py39-sphinx py39-sphinx_rtd_theme py39-alembic py39-chardet py39-enchant \ py39-flask py39-flask-cors py39-appdirs py39-webob py39-waitress py39-websockets py39-qtawesome py39-requests mediainfo \ py39-qdarkstyle py39-appdirs py39-pytest-cov py39-pytest-qt
If you have issues installing the py39-pyobjc-cocoa port or its dependency, py39-pyobjc, then install it with pip instead (this is the current state as of macOS Catalina release):
sudo pip install pyobjc-framework-Cocoa
sudo port -N install hunspell-dict-af_ZA hunspell-dict-ca_ES hunspell-dict-cs_CZ \ hunspell-dict-cy_GB hunspell-dict-de_DE hunspell-dict-el_GR hunspell-dict-en_CA \ hunspell-dict-en_GB hunspell-dict-en_NZ hunspell-dict-en_US hunspell-dict-en_ZA \ hunspell-dict-eo_EO hunspell-dict-es_ES hunspell-dict-es_MX hunspell-dict-fo_FO \ hunspell-dict-fy_NL hunspell-dict-ga_IE hunspell-dict-gd_GB hunspell-dict-gsc_FR \ hunspell-dict-gu_IN hunspell-dict-he_IL hunspell-dict-hi_IN hunspell-dict-hr_HR \ hunspell-dict-id_ID hunspell-dict-ku_TR hunspell-dict-lt_LT hunspell-dict-mg_MG \ hunspell-dict-mk_MK hunspell-dict-ms_MY hunspell-dict-nb_NO hunspell-dict-nl_NL \ hunspell-dict-nn_NO hunspell-dict-nr_ZA hunspell-dict-ns_ZA hunspell-dict-ny_MW \ hunspell-dict-oc_FR hunspell-dict-rw_RW hunspell-dict-sl_SI hunspell-dict-ss_ZA \ hunspell-dict-st_ZA hunspell-dict-sw_KE hunspell-dict-tet_ID hunspell-dict-th_TH \ hunspell-dict-tl_PH hunspell-dict-tn_ZA hunspell-dict-ts_ZA hunspell-dict-uk_UA \ hunspell-dict-ve_ZA hunspell-dict-xh_ZA hunspell-dict-zu_ZA
Install Libraries not in MacPorts
Some Python dependencies are not in MacPorts. These you will need to
sudo pip install pymysql Pyro4 zeroconf pymediainfo PyQtWebEngine python-vlc PyMuPDF
Get rid of session error
After installation of dbus package, you need to load the dbus daemon. Get the commands to run from:
port notes dbus
Otherwise OpenLP might not start correctly!
Keep MacPorts up to date
From time to time newer library versions are available, to install them do first a
sudo port selfupdate
to update MacPorts itself, then run
sudo port upgrade outdated
to upgrade the existing tools and libraries.
Skip to Verifying Your Installation
If you've installed the dependencies using MacPorts, you don't need to install them again with Homebrew.
Install Dependencies with Homebrew (Experimental)
It is not usually a good idea to install MacPorts and Homebrew simultaneously. If you are using MacPorts, as described previously, please skip this section.
Mac OS X Compatibility
Unfortunately Homebrew doesn't allow
macosx_deployment_target to be
set. This means that projects built with Homebrew can only be packaged
for the system used to build them. If you want to package OpenLP to be
compatible with older OS X versions, please use MacPorts, as described
Install Command Line Tools
To install the Command Line Tools, run
xcode-select --install installs gcc or clang (C/C++ compiler) and
other development tools necessary to set up the testing environment via
Download and install Homebrew from http://brew.sh
Update list of available packages
To be able to install latest version of libraries you usually need to tell Homebrew to update the package list:
Install basic development tools
Now we are ready to use Homebrew to install python, libraries and other tools. If you want to use Bazaar, or vim, etc. then you can install them now (if you already have an editor, and/or you want to use the Nightly Build Tarball, then you can skip this):
brew install bzr git wget vim htop-osx
Install Python and Libraries
Now you can install libraries.
Note: The current version of
qt does not include
--with-qtwebkit flag will trigger a source build that
contains the missing
qtwebkit. You may need to
brew remove qt
brew install qt --with-qtwebkit
brew install postgresql python3 enchant
'''Note: The default version of
pyqt provided by
brew does not link
qtwebkit, even if it is correctly installed as described above. The
--build-from-source flag will enable
pyqt to find
may need to
brew remove pyqt first.
brew install pyqt --build-from-source
Then to complete run following:
Note: If this doesn't work, make sure that you have run xcode-select --install as described above.
pip3 install lxml sqlalchemy mako nose beautifulsoup4 psycopg2 sphinx alembic chardet pyenchant PyMySQL
pyobjc takes a very long time to install
pip3 install pyobjc
Dictionaries help with spell checking while writing lyrics and other text in OpenLP. Install the aspell or hunspell dictionaries you like: Homebrew doesn't include hunspell dictionaries, but you can install hunspell as follows, then install compatible dictionaries from external sources. Compatible dictionaries can be found here: http://cgit.freedesktop.org/libreoffice/dictionaries/tree/ Find the *.aff and *.dic files, and install them to the required location. Hunspell dictionaries should be installed to ~/Library/Spelling or /Library/Spelling.
brew install hunspell
Homebrew includes the aspell dictionaries. To see which dictionaries are available, simply run:
brew info aspell
Then use the relevant flags to install the dictionary of your choice. For instance, install all dictionaries with:
brew install aspell --with-all-langs
Or install just English US and UK with:
brew install aspell --with-lang-en --with-lang-uk
Keep Homebrew up to date
From time to time newer library versions are available, to install them, first run:
to update Homebrew itself, then run
to upgrade the existing tools and libraries.
To verify the installation checkout the source code of OpenLP and change to the OpenLP source directory. Then run the following script:
The output should be similar to the following:
bash-3.2$ python3 scripts/check_dependencies.py
Checking Python version...
Python >= 3.0 ... 3.7.4.final.0
Checking for modules...
PyQt5 ... OK
PyQt5.QtCore ... OK
PyQt5.QtGui ... OK
PyQt5.QtWidgets ... OK
PyQt5.QtNetwork ... OK
PyQt5.QtOpenGL ... OK
PyQt5.QtSvg ... OK
PyQt5.QtTest ... OK
PyQt5.QtWebKit ... OK
PyQt5.QtMultimedia ... OK
sqlalchemy ... OK
alembic ... OK
sqlite3 ... OK
lxml ... OK
chardet ... OK
enchant ... OK
bs4 ... OK
mako ... OK
uno ... FAIL
Checking for optional modules...
mysql.connector (MySQL support)... OK
psycopg2 (PostgreSQL support)... OK
nose (testing framework)... OK
jenkins (access jenkins api - package name: jenkins-webapi)... FAIL
Checking for Mac OS X specific modules...
objc ... OK
AppKit ... OK
Verifying version of modules...
PyQt5 >= 5.0 ... 5.5.1
Qt5 >= 5.0 ... 5.5.1
sqlalchemy >= 0.5 ... 1.0.11
enchant >= 1.3 ... 1.6.6
Qt5 image formats...
read: bmp, cur, dds, gif, icns, ico, jp2, jpeg, jpg, mng, pbm, pgm, png, ppm, svg, svgz, tga, tif, tiff, wbmp, webp, xbm, xpm
write: bmp, cur, dds, icns, ico, jp2, jpeg, jpg, pbm, pgm, png, ppm, tif, tiff, wbmp, webp, xbm, xpm
Enchant (spell checker)...
available backends: aspell
available languages: en, en_CA, en_GB, en_US, uk
Assuming all required dependency checks have passed in the previous section, you should be able to run OpenLP. To run OpenLP, simply navigate to your OpenLP development directory, and run
The OpenLP log file is at
See the instructions on setting up SSH on Linux and Mac OS X.
Optional development tools
The following tools are not necessary to run the source code but are useful for debugging and improving code quality:
pip3 install flake8 ipython