FAQ

A Mac with Apple silicon (M1 or later) or a Linux computer (on Windows, WSL), Python 3.11 or later, and an API key from at least one provider (Anthropic, OpenAI, Google, or Mistral). If you download the release ZIP, that is all you need. If you clone the repository, you also need Node 18+ (once, for the first build). ffmpeg is optional — you only need it for video uploads or audio files over about 24 MB.

Download QualiLens.zip from the latest release, unzip it, open a terminal in the folder, and run ./run.sh. The first launch sets up the Python environment automatically. No separate installer.

QualiLens is developed and tested on macOS, and it runs natively on Macs with Apple silicon and on Linux, because the launcher is a shell script (run.sh). On Windows, use WSL (Windows Subsystem for Linux) to run it. The Getting Started page walks through the WSL setup step by step. For more on WSL itself, see Microsoft's Install WSL documentation.

No. A library QualiLens needs for encryption and for checking update signatures is no longer published for Intel Macs, so QualiLens cannot be installed on one. Macs with Apple silicon (M1 or later) are supported.

Open Settings, find the Application card, and press Check for updates. When a newer release exists, Download and install applies it through a validated updater. Your projects, keys, and uploads are not touched by an update.

There is no QualiLens server. Your data go only to the AI provider you chose, over a direct API connection. No telemetry, no analytics, no background connections.

The database (backend/data/qualilens.db) holds everything: projects, source text, codes, excerpts, checkpoints, and reports. Uploaded files sit in backend/data/uploads/. Back up backend/data/ — everything else is regenerated from code.

Yes, from 1.8 on. Keys are stored encrypted in the database, and the secret that unlocks them is a small file outside the data folder — in Application Support on macOS, in ~/.config/qualilens/ on Linux and WSL — readable by your account only. A synced or copied database therefore carries no usable key. What the encryption does not cover: someone using your own account on your own computer can read both files, and the participant data in the database remain plain text. Use Remove in Settings before handing the computer to anyone, and prefer a key with its own spending limit.

Yes. The Privacy page has a section written in the terms ethics committees use — covering processing location, third-party transfer, de-identification, automated decision-making, and reproducibility.

Five: grounded theory, thematic analysis after Braun and Clarke's six phases, qualitative content analysis, framework/deductive coding, and corpus-grounded literature synthesis. Each has its own pipeline, checkpoints, and report figure.

Anthropic (Claude), OpenAI (GPT), Google (Gemini), and Mistral. The model catalog is editable, and you can type any current model ID as a custom choice. Check models in Settings verifies which catalog models the provider still offers to your key; it cannot see quota, so a model marked paid tier only is worth a Test key first.

It depends on the provider, model, method, and corpus size. The wizard shows a cost estimate before you start. A single short transcript typically costs a few cents. Grounded theory with its multiple passes is the most expensive method; content analysis is the cheapest.

Yes — that is the point of checkpoints. At each review stage you can rename, redefine, merge, delete, or add codes. Your edits are final and are not overwritten by later automated stages.

Resume it. Resuming skips work already completed, so you are not re-billed for finished stages. Common causes include rate limiting (HTTP 429), expired keys (HTTP 401), and network drops.

Yes — branch from that checkpoint. A branch copies everything up to that review into a new run and reopens it. The original run and its report stay untouched.

.txt, .md, .docx, .pdf, .mp3, .mp4, .m4a, .wav, .webm. Audio and video are transcribed automatically.

Yes. Transcription runs through OpenAI's Whisper service, regardless of which provider you chose for analysis. Save an OpenAI key in Settings if you plan to upload recordings.

It is probably a scanned PDF that holds page images with no text layer. Run it through OCR first, or supply the transcript as a text file.

The method configuration as the run froze it, narrative sections (overview, findings by theme, integration, limitations), a method-appropriate figure, source buttons that open the coded-source reader, a collapsible evidence section with all codes and their excerpts (unverified ones marked), and an audit appendix with a summary of every checkpoint's decisions; the complete audit log exports as JSON. Literature synthesis adds an extraction table appendix.

Yes. Download .docx builds a formatted document from the same data — Georgia at 11pt, title block, narrative, captioned figure, evidence listing, and audit appendix. The file is named after your project.

Treat it as a draft. The narrative is grounded in the structure you approved, and it is not a findings section you can publish unedited. Read it, revise it, and verify the excerpts against the sources before you use it.

If QualiLens contributes to publishable work, please cite it as:

APA:
Aggarwal, A., & Commuri, S. (2026). QualiLens: A local application for LLM-assisted qualitative data analysis [Computer software]. Zenodo. https://doi.org/10.5281/zenodo.22191913

BibTeX:
@software{qualilens,
  author = {Aggarwal, Ashita and Commuri, Suraj},
  title = {QualiLens: A Local Application for LLM-Assisted Qualitative Data Analysis},
  year = {2026},
  publisher = {Zenodo},
  doi = {10.5281/zenodo.22191913},
  url = {https://doi.org/10.5281/zenodo.22191913}
}

This DOI resolves to the latest version.

Another process holds the port — usually a QualiLens instance you forgot to stop. Either switch to the browser tab it opened, or start on a different port: QUALILENS_PORT=8790 ./run.sh

This browser has not been signed in to the running app. Switch to the tab the launcher opened, or open the launch page its terminal names. If you have neither, stop QualiLens with Ctrl-C and run ./run.sh again. The tab signs itself in as soon as another tab of the same browser has been signed in.

Resume the run — the failure is often transient. If it recurs at the same stage, the source may be producing more output than the token budget allows. Try a different model or split the corpus.

A safety filter blocked the response. Qualitative data about health, violence, or abuse can trigger this. Resume once. A different provider is the practical remedy if the same segment blocks repeatedly.

The AI coder is shown existing codes to encourage reuse, but that listing caps at 120. On a large corpus, later segments may stop seeing early codes. Merge the duplicates at your first checkpoint.