2.1. Installation

QualCoder Installation and running instructions

INSTALLATION

For the manual installations (using the command line or terminal) I mention a specific release version, for example version 3.6. Please check on the releases page for the most current version, as it may be newer.

Prerequisites

VLC is optional, but you will need it installed if you need to do any audio/video coding. Optionally, install ffmpeg for speech to text and waveform display, see https://phoenixnap.com/kb/ffmpeg-windows..

Windows

Use the exe

Current releases contain an exe file. Double-click to run. See https://github.com/ccbogel/QualCoder/releases/

Alternatively install from source

Seriously consider using 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 file (at the bottom of the web site) "Windows installer (64-bit)" 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. Click the green button "Code", and then "Download ZIP". Alternatively, choose the most recent release zip, see 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 and activate the virtual environment.

pip install virtualenv

Create a virtual environment called env.

virtualenv env

Activate the virtual environment, this changes the command prompt display using (brackets): (env)

env\Scripts\activate

7. Install python modules. The py command uses the most recent installed version of python. On soem Windows OS py does not work, instead use 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 Type the following to upgrade the installer:

py -m pip install --upgrade pip

Install the required python modules, this may take 10 minutes.

py -m pip install -r requirements.txt

Wait, until all modules are installed.

8. Run QualCoder from the command prompt:

py -m qualcoder

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

deactivate

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

10. To start QualCoder again:

If you are not using virtual environment, as long as you are in the same drive letter, e.g. C:

py -m qualcoder

If you are using a virtual environment:

cd to the Qualcoder-master (or Qualcoder release folder), then type:

env\Scripts\activate

py -m qualcoder

Debian/Ubuntu Linux

There is an executable file in the releases page for Ubuntu 24.04 for the 3.6 release. Download and double click to run.

Alternatively, run QualCoder from the source code inside a python virtual environment, so that the system installed python modules do not clash and cause problems. I have added the additional code to do this here.

Install venv I am using python3.12 you can choose another recent version if you prefer.

sudo apt install python3.12-venv

Download and unzip the Qualcoder folder.

Open a terminal and move (cd) into that folder. You should be inside the QualCoder-master folder or if using a release, e.g. the Qualcoder-3.6 folder. Inside the QualCoder-master folder:

python3.12 -m venv qualcoder

Activate venv, this changes the command prompt display using (brackets): (qualcoder) Note: To exit venv type deactivate

source qualcoder/bin/activate

Upgrade pip before installing the modules:

pip install --upgrade pip

Install the required python modules, may take 10 minutes:

pip install -r requirements.txt

Install QualCoder (the dot is important):

python3 -m pip install .

To run type

qualcoder

After all this is done, you can deactivate to exit the virtual environment. At any time to start QualCoder in the virtual environment, cd to the Qualcoder-master folder (or Qualcoder-3.6 release folder),

Then type: source qualcoder/bin/activate

Then type qualcoder

Arch/Manjaro Linux

Try downloading the Ubuntu 24 executable and running it with DistroBox https://wiki.archlinux.org/title/Distrobox. Or try downloading the Windows exe and running it in Wine, https://wiki.archlinux.org/title/Wine

Fedora/CentOS/RHEL Linux

Try downloading the Ubuntu 24 executable and running it with DistroBox. Or, try downloading the Windows exe and running it in Wine, https://wiki.archlinux.org/title/Wine

https://www.addictivetips.com/ubuntu-linux-tips/how-to-run-ubuntu-programs-on-fedora-linux/#:~:text=Thankfully%2C%20it%20is%20possible%20to%20run%20Ubuntu%20programs,Ubuntu%20program%20you%20want%20on%20your%20Fedora%20system.

To run from source code:

Please view the Debian instructions above to run QualCoder in a virtual environment.

These install instructions are currently untested

Retrieve the current package code from this repository

git clone https://github.com/ccbogel/QualCoder.git

Make install_fedora.sh executable (chmod +x install_fedora.sh) and run the ./install_fedora.sh script from the terminal. Make sure the qualcoder folder is in the same directory as the install.sh script (i.e. as it appears when you download the QualCoder-master folder). The script is for python version 3.12.

This script installs the dependencies using dnf and the ebook libraries with a work-around, specified at https://github.com/ccbogel/QualCoder/issues/72#issuecomment-695962784.

Fedora uses wayland with does not work well with the Qt graphical interface (for now). I suggest you also install xwayland.

MacOS

Please use the macOS app from the QualCoder 3.6 release page.

The below instructions are to install from the source code. There have been various macOS install issues raised, which is why the various options are shown below.

1. Install a recent version of Python3, e.g. 3.10, 3.11 or 3.12. (Note: Python 3.13 is not supported yet) and VLC. You will also need to install developer tools for macOS. See here: https://www.cnet.com/tech/computing/install-command-line-developer-tools-in-os-x/

2. Download the latest release "Source code" version in ZIP format, from the releases section of the project here on GitHub: https://github.com/ccbogel/QualCoder/releases/tag/3.6 and extract it into /Applications

3. Open the Terminal app (or any other command shell)

4. Install PIP (if not yet installed, try typing pip3 --version and hit ENTER)

curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python3 get-pip.py

-> You should now be able to run pip3 as above.

5. Install Python dependency modules using pip:

pip install -r requirements.txt

If you are on an older, Intel-based Mac, you must perform the following step after installing all the other requirements (only for version 3.6 and above):

pip install "numpy<2" # don't forget the quotation marks

Be sure that you are in the QualCoder-Master directory before doing Step 6.

To change the directory, enter or copy and run the script below.

cd /Applications/QualCoder-3.6

From the QualCoder-Master directory run the setup script:

6. python3 -m pip install .

Assuming you downloaded the 3.6 version. You can now run with:

python3 /applications/QualCoder-3.6/qualcoder/__main__.py

Alternative commands to run QualCoder (Suggestions):

From any directory:

qualcoder

From the QualCoder-Master directory:

python3 -m qualcoder

You can install QualCoder anywhere you want, so the path above depends on where you extracted the archive.

Another option to run Qualcoder is shown here: https://www.maketecheasier.com/run-python-script-in-mac/. This means you can right-click on the qualcoder.py file and open with --> python launcher. You can make an alias to the file and place it on your desktop.

Another option to install on Mac:

Open the Terminal App and move to the unzipped Qualcoder-Master directory, then run the following commands:

pip3 install -U py2app or for a system installation of python sudo pip3 install -U py2app

python3 setup.py py2app