FAQ

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. The launcher is a shell script (run.sh), so it runs natively on macOS and Linux. On Windows, use WSL (Windows Subsystem for Linux) to run it.

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 never touched by an update.

There is no QualiLens server. Your data goes 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.

No. Keys are stored as plain text in the database. They are not encrypted and not held in a system keychain. Use Remove in Settings before sharing the folder, 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, reflexive thematic analysis, 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 are still served.

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 every review stage you can rename, redefine, merge, delete, or add codes. Your edits are final and are never overwritten by later automated stages.

Resume it. Resuming skips work already completed, so you are never 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, .rtf, .mp3, .mp4, .m4a, .wav, .webm. Audio and video are transcribed automatically.

Yes. Transcription always 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.

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 every code and its excerpts, and an audit appendix. 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 always resolves to the latest version.

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

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.