QualCoder Installation and running instructions¶

Pick the latest release.

You have two options for executables created on Windows 11:

Option 1: There is a Windows installer on the release page called: QualCoder.Win.exe

Option 2: There is a standalone, non-installable exe folder called: QualCoder.Win.Portable.zip Download and unzip. It is in a folder alongside an internal folder. These both must be together or the exe will not run. Double-click the QualCoder exe to run, it takes up to 20 seconds to start.

Standalone, portable version:

On first use of the exe, Windows will 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 code:

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 a recent version 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"

1. 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.

2. 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).

3. 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)

4. 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.8.2 folder). e.g.

cd Downloads\QualCoder-master

5a. Instead of the next below commands, run the bat file which will run all these commands below, by typing this in and pressing Enter:

run_from_source_Windows.bat

If you get errors using a bat file, then run the below commands instead.

1. Install the virtual environment and required python modules.

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

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

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

cd src
python -m qualcoder

1. 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:

python -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
python -m qualcoder

Install from App bundles:

Make sure you have installed any macOS updates before starting the installation. Go to the System Settings app on your Mac. Click General in the sidebar (you may need to scroll down), then click Software Update.

Install QualCoder: Double-click the downloaded dmg-file. Drag QualCoder into the link to your applications.

Start QualCoder from your Launchpad or by double-clicking the app within your applications folder. We are currently not able to sign the app bundles, so when you first try to run the program, you may get a pop-up warning that QualCoder is from an unregistered developer or "QualCoder can't be opened because Apple cannot check it for malicious software." Depending on your processor, you may see one of these:

If you see "Show in Finder" or OK. Click Ok.

If you see "Done" or "Move to trash". Click Done.

Next, go to Settings and select Privacy and Security. Scroll down until you see a message stating QualCoder was prevented from starting. Click on "open anyway". You may be prompted to enter your password and may need to click "Open" again. After entering your password, just wait for the program to open up. It may take several seconds.

From now on, QualCoder should start without issues.

You can install QualCoder without admin right. You must copy the binaries in /Users/mylogin/Applications directory. You must delete the attribute on the application directory, typing on the terminal: xattr -d com.apple.quarantine /Users/mylogin/Applications/QualCoder.app

Install from source code:

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

1. 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

1. Run QualCoder from the command prompt

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

1. 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

If you are using a Debian-based system (Debian, Ubuntu / Lubuntu / ZorinOS, Linux Mint), there is an executable file available on the release page. Download and double click to run. You might first need to right-click on the file and go to Properties, then check the Executable checkbox.

If you are using a different operating system, please install from the source code. The procedure is set out below.

Note: Fedora uses Wayland which may not work well with the Qt graphical interface. It is suggested you also install Xwayland.

To install from source code below, inside a virtual environment.

Depending on your operating system, you will need to download Python and its dependencies. Here are the commands for your operating system:

• If you are on Debian based system (Debian, Ubuntu / Lubuntu / ZorinOS, Linux Mint) : Install pip. This is a tool that downloads extra python modules : sudo apt install python3-pip If you are using audio or video, install VLC (download from site) or: sudo apt install vlc If you are using the alternative Ubuntu Desktop manager Xfce you may need to run this: sudo apt install libxcb-cursor0
• If you are on Fedora : There is a problem with using VLC from python. The software crashes, we are unable to find a solution to this. So audio and video cannot be used within a QualCoder project on Fedora.

• If you are on Arch/Manjaro Linux : If you are using audio or video, install VLC (download from site) or: sudo pacman -S vlc and Install pip and venv: sudo pacman -S python python-pip python-virtualenv

• Download and unzip the Qualcoder folder.

• Then cd to the QualCoder folder.

For example, you may now be in this folder, where you unzipped QualCoder:

yourcomputer:~Downloads/QualCoder-3.8.2

3a. Instead of the commands from 3b. onwards, run the shell file which will run all these below commands. Make this file executable (Right-click and go to Properties), then type the below command and press Enter:

./run_from_source_Linux.sh

3b. Set up virtual environment and install python modules. The virtual environment will be in its own folder called env. Installing required modules takes a while.

python3 -m venv env
source env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

1. Move to the inner src folder, then:

   cd src
   python3 -m qualcoder
   

2. After using QualCoder deactivate the virtual environment.

deactivate

Usage any time after the install, move to the QualCoder folder then:

source env/bin/activate
cd src
python3 -m qualcoder

To exit the environment:

deactivate

You can also make a .desktop file for launching QualCoder:

Create a .Desktop file for launch, enter this command (adapt it according to the location of the source code folder):

bash -c 'cd ~/.local/share/qualcoder/src/ && ~/.local/share/qualcoder/env/bin/python3.12 -m qualcoder'