MacOS Install Instructions Require Review & Updates

[rcurty]

I installed version 3.5 months ago without any issues, but the current instructions for macOS are causing multiple problems. For instance, the instructions mention installing dependencies from a requirements.txt file, but this file is missing from the distribution. Additionally, frequent warnings related to the x86 vs. M1 architecture complicate the installation process further. Other error messages have also appeared, making it difficult to follow the steps successfully. It would be helpful if those could be tested and reviewed and the documentation updated to reflect the latest changes and address compatibility for MacOS users. Thank you!

[ccbogel]

Thanks for the information,
For now I would remain using the 3.5 version that was released last year. When the 3.5 zip is downloaded it contains macOS install instructions in the README.md document.

I do not have a mac to test or check how the install process works. I am reliant on others to provide the install instructions needed for macOS.
The latest code with the 3.6 version is still very much in development with the AI features needing more testing on more operating systems, such as macOS. The details of the error messages would be beneficial. As others can comment and provide advice how to resolve them. And then incorporate into the instructions to set QualCoder up on mac.

While it does not cover the most current code, I have been told that some people run the 3.5 Windows exe version within Wine on macOS.

[kaixxx]

@rcurty: Thank you for bringing this up. There was indeed an error in the instructions for macOS. In step 2, you must download the current code, using the green code button in the upper right and "download zip". (The old instructions were directing you to the latest released code, which is still 3.5)

I have now corrected the instructions in the readme. Could you please try again? As Colin already mentioned, we really need people that test the new version on macOS. It would be great if you could help a little with that. Thanks!

[rcurty]

@ccbogel and @kaixxx:
Thank you for getting back to me so quickly! To clarify, we encountered an issue while attempting to install version 3.5, not 3.6. I had it installed on my laptop months ago with no problems. I am currently teaching a workshop using QualCoder (3.5) here since this is the more stable version. For this session, we’ve set up a Windows VM environment for Mac users to bypass the multi-step installation process for Macs. Once the workshop concludes next week, I will follow the updated installation instructions and test them. If I encounter any challenges during this process, I’ll be sure to reach out. We expect some learners to want to install QualCoder on their devices; understanding the new installation process for Mac users will be very helpful. Thanks again!

[kaixxx]

If you want to use the 3.5 release, make sure to follow the instructions in the readme.md file that comes with the download.

Good luck with your workshop! I'm curious to know how you like the new version 3.6 A few students of mine installed it on macOS, and it seems to work fine.

[tomasruizt]

@kaixxx For the LMU workshop I installed the qualcoder program in MacOS Sequoia 15.1. I had to remove the version restriction in requirements.txt for two libraries: chroma-hnswlib and chromadb. It might be that removing the restriction on chromadb is sufficient. Otherwise, I was getting this error during the pip install -r requirements.txt step:

...
Using cached pygments-2.18.0-py3-none-any.whl (1.2 MB)
Using cached rsa-4.9-py3-none-any.whl (34 kB)
Using cached wrapt-1.17.0-cp312-cp312-macosx_11_0_arm64.whl (38 kB)
Using cached zipp-3.21.0-py3-none-any.whl (9.6 kB)
Using cached pycparser-2.22-py3-none-any.whl (117 kB)
Using cached mdurl-0.1.2-py3-none-any.whl (10.0 kB)
Using cached pyasn1-0.6.1-py3-none-any.whl (83 kB)
Building wheels for collected packages: chroma-hnswlib
  Building wheel for chroma-hnswlib (pyproject.toml) ... error
  error: subprocess-exited-with-error
  
  × Building wheel for chroma-hnswlib (pyproject.toml) did not run successfully.
  │ exit code: 1
  ╰─> [18 lines of output]
      running bdist_wheel
      running build
      running build_ext
      creating var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T
      clang++ -fno-strict-overflow -Wsign-compare -Wunreachable-code -DNDEBUG -g -O3 -Wall -I/opt/homebrew/opt/llvm/include -I/Users/tomasruiz/code/qualcoder/venv/include -I/Users/tomasruiz/.pyenv/versions/3.12.4/include/python3.12 -c /var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T/tmp65z_7v4p.cpp -o var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T/tmp65z_7v4p.o -std=c++14
      clang++ -fno-strict-overflow -Wsign-compare -Wunreachable-code -DNDEBUG -g -O3 -Wall -I/opt/homebrew/opt/llvm/include -I/Users/tomasruiz/code/qualcoder/venv/include -I/Users/tomasruiz/.pyenv/versions/3.12.4/include/python3.12 -c /var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T/tmp0169vfzn.cpp -o var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T/tmp0169vfzn.o -fvisibility=hidden
      building 'hnswlib' extension
      creating build/temp.macosx-14.5-arm64-cpython-312/python_bindings
      clang++ -fno-strict-overflow -Wsign-compare -Wunreachable-code -DNDEBUG -g -O3 -Wall -I/opt/homebrew/opt/llvm/include -I/private/var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T/pip-build-env-z0accz27/overlay/lib/python3.12/site-packages/pybind11/include -I/private/var/folders/qr/_v5_781s2dng7yqfszqps_xw0000gn/T/pip-build-env-z0accz27/overlay/lib/python3.12/site-packages/numpy/_core/include -I./hnswlib/ -I/Users/tomasruiz/code/qualcoder/venv/include -I/Users/tomasruiz/.pyenv/versions/3.12.4/include/python3.12 -c ./python_bindings/bindings.cpp -o build/temp.macosx-14.5-arm64-cpython-312/./python_bindings/bindings.o -O3 -stdlib=libc++ -mmacosx-version-min=10.7 -DVERSION_INFO=\"0.7.3\" -std=c++14 -fvisibility=hidden
      In file included from ./python_bindings/bindings.cpp:1:
      In file included from /opt/homebrew/Cellar/llvm/19.1.2/bin/../include/c++/v1/iostream:42:
      In file included from /opt/homebrew/Cellar/llvm/19.1.2/bin/../include/c++/v1/ios:220:
      In file included from /opt/homebrew/Cellar/llvm/19.1.2/bin/../include/c++/v1/__locale:14:
      /opt/homebrew/Cellar/llvm/19.1.2/bin/../include/c++/v1/__locale_dir/locale_base_api.h:29:12: fatal error: 'xlocale.h' file not found
         29 | #  include <xlocale.h>
            |            ^~~~~~~~~~~
      1 error generated.
      error: command '/opt/homebrew/opt/llvm/bin/clang++' failed with exit code 1
      [end of output]
  
  note: This error originates from a subprocess, and is likely not a problem with pip.
  ERROR: Failed building wheel for chroma-hnswlib
Failed to build chroma-hnswlib
ERROR: Could not build wheels for chroma-hnswlib, which is required to install pyproject.toml-based projects

[kaixxx]

Thank you very much. QualCoder needs more testing on Mac, so it's very helpful to get such feedback. The version restrictions for chromadb and chroma-hnswlib are related to an issue on Windows only, so it's probably fine to use a newer version on Mac. I will try to edit the requirements.txt accordingly.

See you in Munich next week!

[kaixxx]

@tomasruizt Could you try this requirements.txt on macOS: https://github.com/kaixxx/QualCoder/blob/ai_finalize/requirements.txt

[tomasruizt]

@tomasruizt Could you try this requirements.txt on macOS: https://github.com/kaixxx/QualCoder/blob/ai_finalize/requirements.txt

Installing using this requirements.txt file solved my installation issue

[kaixxx]

@tomasruizt: Thank you for testing! I have now included this change into the master branch: 1ee5359

[vansorat]

Using MacOS Ventura 13. Installed QualCoder Master Code today 1/28 and received error when running this script.
pip3 install -r requirements.txt

ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

I continued with next script and was able to install and run 3.6.
I had installed earlier in January without this error.
What is the purpose of the requirements.tx and how might it affect what I can do? Thanks.

[kaixxx]

What is the purpose of the requirements.tx and how might it affect what I can do? Thanks.

The requirements.txt contains a list of the required python packages to run QualCoder. Using pip3 install -r requirements.txt is a convenient way to install them all in one go. In your case, this wasn't necessary since you have already installed everything a few weeks ago. It is, however, always advisable to update to the latest requirements because there might be changes.

ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'requirements.txt'

Make sure that you are in the root directory of the downloaded QualCoder code, or pip won't be able to find the requirements.txt file. Use cd <QualCoder root path> in the terminal to change to that directory, if needed.

[vansorat]

I had the folder in Downloads so I moved it to Applications. Rather than use change directory, I opened Finder and right click on Qualcoder-master folder and selected New Terminal at folder. I then entered the scrip pip3 install -r requirements.txt and it works. So maybe direction to change directory should go before this. So step 6 should be step 5 and placing that instruction before step 5?

5. Install Python dependency modules using pip:
   pip3 install -r requirements.txt
   Be sure that you are in the QualCoder-Master directory before doing Step 6.

Thanks!

[kaixxx]

You are right, I have changed it: 0c61a6f
Thanks and nice to hear that it works now.

[vansorat]

Thank you for making the change .
I have a few more suggestions for MacOS installation. I am not a MAC user so this might help others.

1. Mac might unzip the downloaded code zip folder automatically and then it sits in download. If not unzipped, unzip the folder. Move the folder to Applications. These instructions assume the folder is in Applications.
2. As an alternative to typing cd and the file path to change directory, open Finder, open Applications, and right click on the QualCoder-master folder and select "New Terminal at Folder" . You will now be in the QualCoder directory. If you did not put the folder in Applications then go to where the folder is and select New Terminal at folder from there.
3. If you do not have the developer code, just start the installation process and you will be prompted to install. This may be easier than figuring out if you have it or how to get it. Expect this process to take a long time.

[ccbogel]

OK thanks for this. I have updated the macOS install instructions.

[vansorat]

on a MAC OS Big Sur v 11 intel
I am not sure if I have an issue with my path
When I type python --version, 3.8 shows up (I think it was bundled with a stat program)
When I type python3 I get 3.12
Typing Env I got this:
USER=Vansorat
PATH=/Library/Frameworks/Python.framework/Versions/3.12/bin:/Library/Frameworks/Python.framework/Versions/3.11/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
SHLVL=1
PWD=/Users/Vansorat
OLDPWD=/Users/Vansorat
LANG=en_US.UTF-8
_=/usr/bin/env

Mastercode was installed but I ran into this error when launching:

Vansorat@Vansorat QualCoder-master % python3 /applications/QualCoder-master/qualcoder/main.py
Traceback (most recent call last):
File "/applications/QualCoder-master/qualcoder/main.py", line 42, in
from PyQt6 import QtCore, QtGui, QtWidgets
ImportError: dlopen(/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/PyQt6/QtCore.abi3.so, 2): Symbol not found: _kIOMainPortDefault
Referenced from: /Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/PyQt6/Qt6/lib/QtCore.framework/Versions/A/QtCore (which was built for Mac OS X 12.0)
Expected in: /System/Library/Frameworks/IOKit.framework/Versions/A/IOKit

Running 3.5 gets same error
Traceback (most recent call last):
File "/applications/QualCoder-3.5/qualcoder/main.py", line 47, in
from PyQt6 import QtCore, QtGui, QtWidgets
ImportError: dlopen(/Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/PyQt6/QtCore.abi3.so, 2): Symbol not found: _kIOMainPortDefault
Referenced from: /Library/Frameworks/Python.framework/Versions/3.12/lib/python3.12/site-packages/PyQt6/Qt6/lib/QtCore.framework/Versions/A/QtCore (which was built for Mac OS X 12.0)
Expected in: /System/Library/Frameworks/IOKit.framework/Versions/A/IOKit

[vansorat]

I think pip install "numpy<2" need to read pip3 install.... with a 3 after pip

[ccbogel]

"I think pip install "numpy<2" need to read pip3 install.... with a 3 after pip"
I think this is because for you, you have multiple python versions installed, it wont be the same for everyone.

looking here for a solution: https://stackoverflow.com/questions/60761175/how-to-solve-importerror-dlopen-symbol-not-found-expected-in-flat-name

Perhaps try, with pip or pip3:
pip uninstall pyqt6 and then pip install --no-cache-dir pyqt6

Also, as you have python 3.12 installed, can try this, which ensure the re-install is for the python 3.12 version :
Perhaps try, with pip or pip3:

python3.12 -m pip install --upgrade pip
Then:
python3.12 -m pip uninstall pyqt6 and then pip install --no-cache-dir pyqt6

[kaixxx]

Hi all,
with today's release of version 3.6, we have also added DMG app bundles for macOS, hoping to make the setup on Mac a little easier. There is a version for the newer Macs with Apple Silicon (M1...M4-processors) and the older Intel-based ones. It would be great if somebody could test the Intel-version, since I only have access to a M1 Mac.

The current release: https://github.com/ccbogel/QualCoder/releases/tag/3.6 Make sure to follow the installation instructions at the top of the release page.

(There is a small issue with the visibility of the icons in the "original" style. So, I would suggest switching to the "native" style in the settings.)