<img src="https://github.com/ccbogel/QualCoder/blob/master/qualcoder.png" width=200 height=200>

README QualCoder in other languages : [Français]

QualCoder

QualCoder is a qualitative data analysis application written in Python.

Text files can be typed in manually or loaded from txt, odt, docx, html, htm, md, epub, rtf and PDF files. Images, video, and audio can also be imported for coding. Codes can be assigned to text, images, and a/v selections and grouped into categories in a hierarchical fashion. Various types of reports can be produced including visual coding graphs, coder comparisons, and coding frequencies. AI models like GPT-4 from OpenAI can be used to explore your data and analyze the results.

This software has been used on MacOS and various Linux distros. Instructions and other information are available here: https://qualcoder.wordpress.com/ and on the Documentation.

It is best to download the Current Release from the Releases page: https://github.com/ccbogel/QualCoder/releases

If you like QualCoder please buy me a coffee ...

<a href="https://www.buymeacoffee.com/ccbogelB" target="_blank"><img src="https://cdn.buymeacoffee.com/buttons/default-orange.png" alt="Buy Me A Coffee" height="41" width="174"></a>

INSTALLATION

Prerequisites

Optional: VLC for audio/video coding. Optional: ffmpeg installed for waveform image see here to install ffmpeg on Windows: https://phoenixnap.com/kb/ffmpeg-windows.

On the first start of QualCoder, you may want to setup the AI enhanced features as described below.

Windows

You have two options, see Releases link on the right-hand side of this page:

• Newer releases contain an exe file created on Windows 11. Double-click to run, it takes 20 seconds to start.
• There are Windows installers available on the release page.

On first use of the exe, Windows may ask you to allow to run QualCoder. This is because it is from an unknown publisher. It costs a lot of money to get a trusted publisher certificate - so that will not be possible for the foreseeable future. If you are uncomfortable with these warnings install from the source as detailed next.

Alternatively, install from source:

Use a virtual environment (commands in point 6 below). Not using a virtual environment may affect other Python software you may have installed.

1. Download and install the Python programming language. Please use Python 3.11 to 3.14 on Windows. Python3. Download the latest "Windows installer (64-bit)" (or the one matching your architecture) for one of the above mentioned Python versions.

IMPORTANT: in the first window of the installation mark the option "Add Python to PATH"

2. Download the QualCoder software from: https://github.com/ccbogel/QualCoder from the Green Code button. This is the newest, but not yet officially released code (occasionally coding errors creep in). Click the green button "Code", and then "Download ZIP". Alternatively, choose the most recent release zip, see the right-hand side of this page for the link to Releases.

3. Unzip the folder to a location (e.g. downloads). (Tip, remove the doubled-up folder extraction QualCoder-master\QualCoder-master when asked where to extract. Just QualCoder-master).

4. Use the Windows command prompt. Type "cmd" in the Windows Start search engine, and click on the black software "cmd.exe" - the command console for Windows. In the console type or paste, using the right-click mouse copy and paste (ctrl+v does not work)

5. In the command prompt, move (using the cd command) into the QualCoder folder. You should be inside the QualCoder-master folder or if using a release (the Qualcoder-3.6 folder). e.g.

cd Downloads\QualCoder-master

6. Install the virtual environment and required python modules.

The py command uses the most recent installed version of Python. The py command does not work on all Windows OS, you may instead replace py with python3. You can use a specific version on your Windows if you have many Python versions installed, e.g. py -3.12. See discussion here: Difference between py and python

The install may take up to 10 minutes. On some Windows systems you may need to replace the py command with python or python3 below:

py -m venv env
env\Scripts\activate
py -m pip install --upgrade pip
py -m pip install -r requirements.txt

7. Start QualCoder. by moving to the the inner src folder first:

cd src
py -m qualcoder

If you are using python version 3.13 and get a dll error regarding the torch module when trying to run QualCoder. Install this torch version:

pip install torch==2.8.0

8. If running QualCoder in a virtual environment, to exit the virtual environment type:

deactivate

The command prompt will then remove the (env) wording.

To start QualCoder again

If you are not using a virtual environment, as long as you are in the same drive letter, eg C:

py -m qualcoder

If you are using a virtual environment:

cd to the src folder inside the Qualcoder-master (or Qualcoder release folder):

env\Scripts\activate
cd src
py -m qualcoder

MacOS

Attached to the current release linked at the right side of this page, you will find two options ('X' representing the current version):

• QualCoder_X_arm64.dmg: App bundle for newer Macs with Apple Silicon (M1 ... M4 processors)
• QualCoder_X_x86_64.dmg: App bundle for the older Macs with Intel processor (core i5, i7, etc).

The app bundles are compiled on macOS Sequoia. They might also work on Sonoma and Ventura. If you are on an older version, consider updating your OS or install QualCoder from source as described below.

Note: We are currently not able to sign the app bundles, so you will get a warning that QualCoder is from an unregistered developer. You have to manually allow the app to be executed, if your Gatekeeper is active. Follow these steps:

• Double-click the downloaded dmg-file.

• Drag QualCoder into the link to your applications (ignore the __main__ folder also in the window).

• Start QualCoder by double-clicking the app within your applications folder. You will get an error that QualCoder is from an unregistered developer. The app will not start.

• Go to Settings -> Privacy and Security -> Scroll down until you see a message stating QualCoder was prevented from starting. Click on "open anyway".

• From now on, QualCoder should start without issues.

• Sometimes VLC might not be detected. One solution to try is to install VLC via Homebrew.

If these app bundles do not work for you and you want to run QualCoder from source, follow these steps:

Alternatively, install from source:

Use a virtual environment (commands in point 6 below). Not using a virtual environment may affect other Python software you may have installed.

1. Download and install the Python programming language. Please use Python 3.10, 3.11 or 3.12 on Windows, other versions may cause issues Python3. Download the latest "macOS 64-bit universal2 installer" for one of the above mentioned Python versions and open it to install Python.

2. Download the QualCoder software from: https://github.com/ccbogel/QualCoder from the Green Code button. This is the newest, but not yet officially released code (occasionally coding errors creep in). Click the green button "Code", and then "Download ZIP". Alternatively, choose the most recent release zip, see the right-hand side of this page for the link to Releases.

3. Unzip the folder to a location (e.g. downloads) by double-clicking it.

4. Use the Terminal app (Applications -> Utilities -> Terminal).

5. In the terminal, move (using the cd command) into the QualCoder folder. You should be inside the QualCoder-master folder or if using a release (e.g. Qualcoder-3.8.2 folder). e.g.

cd Downloads/QualCoder-master

6. Install the virtual environment and required python modules.

The python3 command uses the most recent installed version of Python. You can use a specific version on your macOS, if you have many Python versions installed, e.g. python3.10. To verify you are using the correct Python version type which python3, which should output: /Library/Frameworks/Python.framework/Versions/3.<version>/bin/python3. If the output is /usr/bin/python3, don't continue, since this is your system's Python and it is discouraged to use.

The install may take up to 10 minutes.

python3 -m venv env # this creates the virtual environment with the name "env" in your current directory
source env/bin/activate # this activates the virtual environment "env", (env) should appear in front of your prompt
pip3 install --upgrade pip # optionally; pip and pip3 are equivalent withing a virtual environment
pip3 install -r requirements.txt

7. Run QualCoder from the command prompt

cd src
python3 -m qualcoder # python and python3 are equivalent withing a virtual environment

8. If running QualCoder in a virtual environment, to exit the virtual environment type:

deactivate

The command prompt will then remove the (env) wording.

To start QualCoder again

If you are not using a virtual environment:

cd Downloads/QualCoder-master
cd src 
python3 -m qualcoder

If you are using a virtual environment:

cd Downloads/QualCoder-master
source env/bin/activate
cd src 
python3 -m qualcoder

Linux

Ubuntu / Lubuntu / ZorinOS

To install from source code below, inside a virtual environment. If you are using the alternative Ubuntu Desktop manager Xfce you may need to run this: sudo apt install libxcb-cursor0

1. If you are using audio or video, in