Install and update
The Windows installer, the Linux AppImage, .deb and .rpm, what the security warnings mean, how updates arrive, where your files live, and how to uninstall.
Where to download
The only official source is the project's Releases page on GitHub: github.com/PurpleDoubleD/locally-uncensored/releases/latest. The download button on this site and on lu-labs.ai points at the same release. Every release carries one Windows installer and three Linux packages, built by GitHub Actions from the public source. There is no Mac build.
The file names on the Releases page follow this pattern, with the version number in the middle:
| Platform | File |
|---|---|
| Windows 10 and 11, x64 | Locally.Uncensored_3.0.0_x64-setup.exe |
| Linux x64, any distribution | Locally.Uncensored_3.0.0_amd64.AppImage |
| Debian, Ubuntu, Mint | Locally.Uncensored_3.0.0_amd64.deb |
| Fedora, openSUSE | Locally.Uncensored-3.0.0-1.x86_64.rpm |
The installer itself is small (about 14 MB on Windows). The models, the ComfyUI install and the PyTorch download come later, from inside the app, and those are the big files.
Windows
Double-click the .exe. Windows SmartScreen usually shows a blue "Windows protected your PC" box first, because the installer is not yet signed with a Microsoft certificate. Read the section on warnings below before you decide what to do with that box.
The installer asks for a language, then whether to install for the current user only or for all users. Either works; the current user option needs no administrator password. It then copies the app and the LU Engine into the install folder, creates a desktop shortcut and a start menu entry named "Locally Uncensored", and offers to start the app.
The first start opens the setup wizard in its own small window. Chapter 3 walks through it. The LU Engine listens only on your own machine (127.0.0.1) unless you turn on remote access or the Local API in Settings, so nothing is reachable from the network by default.
Linux
Three packages are built for every release. Pick one:
Download the .AppImage, mark it executable and run it:
chmod +x Locally.Uncensored_3.0.0_amd64.AppImage
./Locally.Uncensored_3.0.0_amd64.AppImageThe AppImage bundles the LU Engine and the media framework. It needs the Vulkan loader (libvulkan1 on Debian and Ubuntu, vulkan-loader on Fedora) and the OpenMP runtime (libgomp1 or libgomp) on the system, because the engine loads them at start. Most desktop installs have both. If one is missing, the engine tells you the package name, and chapter 9 lists the sentence.
sudo apt install ./Locally.Uncensored_3.0.0_amd64.deb
sudo dnf install ./Locally.Uncensored-3.0.0-1.x86_64.rpmBoth packages declare their dependencies, including libvulkan1 and libgomp1 (or their Fedora names), so the package manager pulls them in. They put two programs into /usr/bin: locally-uncensored and lu-llama-server, the engine. The app appears in the application menu as "Locally Uncensored".
A community maintained AUR package, locally-uncensored-bin, unpacks the .deb into /usr. The project does not maintain it and cannot update it. The app's own updater recognises an install that a package manager owns and handles it as described under updates below.
WEBKIT_DISABLE_DMABUF_RENDERER=1, WEBKIT_DISABLE_COMPOSITING_MODE=1, and, in the AppImage only, LD_PRELOAD pointing at the system libwayland-client.so.0, because the AppImage carries its own copy and the host Mesa cannot create an EGL display against it. The app sets each one only if you have not set it yourself, and it prints one line per variable with the reason. If you want the GPU path back, set any of those variables before starting the app and the app leaves your value alone, or set LU_NO_WAYLAND_WORKAROUND=1 and it sets none of them. The AppImage also clears PYTHONHOME and PYTHONPATH for every Python it starts, because the AppImage runtime exports them into its own mount and a system Python would otherwise die on "No module named 'encodings'".
What the security warnings mean
The Windows installer is built with NSIS and is not yet signed with a Microsoft Authenticode certificate. Without that certificate every reputation based check starts at zero trust, so three things happen: Windows SmartScreen shows "unrecognized app" on first run, some antivirus engines flag the file with a heuristic (Avast, for example, has reported Win32:NSIS_Error[Heur] on the installer bootstrap, and ESET has blocked it at run time), and behaviour scanners dislike that the app later downloads and starts other programs (the engine, ComfyUI, Python, model files). All of those downloads are visible in the source code. The project's SECURITY.md keeps the current list of reports.
What you can check yourself, before you click past a warning:
- The file came from the Releases page linked above, not from a mirror or a forum. Compare the file name and version with the release you meant to download.
- The SHA-256 of your download matches the one GitHub lists for that asset. On Windows:
certutil -hashfile Locally.Uncensored_3.0.0_x64-setup.exe SHA256. On Linux:sha256sum <file>. The same hash appears on VirusTotal if you scan the file there. - The auto update channel, which brings every later version, is signed with a minisign key that the app verifies before it installs anything. The public key is printed in SECURITY.md. So the first install is the only unsigned step.
A warning is not proof that a file is safe or malicious. If the source or the checksum does not match, stop and do not run the file. If they match and you still cannot establish trust, ask in the Discord or open an issue; a false positive is possible, and it must be investigated rather than assumed. Do not add a blanket folder exclusion to your antivirus for it.
How updates arrive
The app checks GitHub Releases for a newer version five seconds after every start and then every six hours. It reads a small file called latest.json that the release carries, and it only ever offers versions the project has marked as the latest.
When a newer version exists, a badge appears in the top bar reading "Update to v3.0.1" (with the real number). Because "Download updates automatically" is on by default under Settings, General, Updates, the app fetches the update in the background right away and the badge changes to "Updating 42%" and then to "Restart to update". Nothing restarts on its own; the update installs only when you click.
Clicking the badge opens a small panel headed "Update Available", "Downloading Update", "Ready to Install", "Installing..." or "Update Error". Its buttons are "Download Update" and "Later" before the download, "Restart Now" and "Later" once it is ready, and "Retry" and "Dismiss" after an error. The same controls sit under Settings, General, Updates, together with "Current Version", "Latest Version" and "Check for updates".
The app stops the LU Engine, writes your chats to disk and takes a copy of them outside the browser profile (the same backup it writes every five seconds while you use it), then hands over to the installer. On Windows that is the same NSIS installer as the first install; on a .deb or .rpm install it is a package install, and your system asks for your password the way it does for any package. Chats, settings and models live outside the install folder and survive the update.
On Linux installs the updater cannot write (an AppImage in a read only folder, an install a package manager owns such as the AUR package, or files nothing owns), the app updates itself instead: it downloads a signed AppImage into ~/.local/share/locally-uncensored/, writes a start menu entry that points at it, and starts again from there. The progress line shows the three short steps after the download: "Checking the signature", "Putting the new version in place", "Starting the new version". From then on updates are the usual one click.
Where your files live
Nothing of yours lives in the install folder. Everything is under your user profile, in these places:
| What | Windows | Linux |
|---|---|---|
| App data, logs, ComfyUI by default | %LOCALAPPDATA%\lu-labs | ~/.local/share/lu-labs |
| Log files (one per day, seven kept) | %LOCALAPPDATA%\lu-labs\logs\lu.<date>.log | ~/.local/share/lu-labs/logs/lu.<date>.log |
| LU Engine model files (.gguf) | %APPDATA%\Locally Uncensored\models | ~/.local/share/Locally Uncensored/models |
| Chat backup copies | %APPDATA%\Locally Uncensored\store_backup.json | ~/.local/share/lu-labs/stores/store_backup.json |
| ComfyUI path, port and trainer root | %APPDATA%\locally-uncensored\config.json | ~/.config/locally-uncensored/config.json |
| Agent sandbox folders | %USERPROFILE%\agent-workspace | ~/agent-workspace |
| Character trainer (venv, base models, training sets) | the trainer root in config.json, by default musubi under the app data folder | |
Your conversations themselves are kept in the app's browser storage (IndexedDB), not in a file you can open. The backup file above is a snapshot of them that the app writes every five seconds and rotates through three generations, and it is what an update or a reset falls back on. To move chats between machines use "Export all chats" and "Import chats" under Settings, General, Chat Backup. The LU Engine model folder can be moved to another drive under Settings, AI Backends, Model Storage.
The ComfyUI the app installs lands in your home folder by default (~/ComfyUI), or in the path you set under Settings, AI Backends, ComfyUI (Image & Video) before pressing "Install ComfyUI". Its models live inside it under models/.
Uninstall
Windows: use "Apps" in the Windows settings, or the uninstaller entry in the start menu. The uninstaller removes the install folder and the shortcuts. It shows a checkbox that also deletes the app data; leave it unticked and your chats, settings and models stay in the folders listed above, so a later reinstall finds them again.
Linux: sudo apt remove locally-uncensored or sudo dnf remove locally-uncensored for the packages; for the AppImage, delete the file. Neither touches the folders under your home directory. Delete ~/.local/share/lu-labs, ~/.local/share/Locally Uncensored, ~/.config/locally-uncensored and ~/ComfyUI yourself if you want everything gone, and the file the self updater may have placed under ~/.local/share/locally-uncensored/ together with its entry in ~/.local/share/applications/.
When it goes wrong
SmartScreen shows "Windows protected your PC" and only offers not to run the file. Click "More info" in that box to reveal the other button. Before you use it, do the checks in the warnings section above. If the checks fail, do not run it.
The antivirus removed the file right after the download. Leave it in quarantine while you check the detection name in the antivirus history and compare the download's checksum with the Releases page. Report the version, the file name and the detection name in a GitHub issue. Do not add a folder exclusion.
The installer says a file is in use. A LU Engine from an earlier session is still running. The installer frees it by itself and, if it still cannot write after four tries, moves the old file aside as lu-llama-server.exe.old and continues. If the installer still stops, quit the app from the tray icon ("Quit") and run the installer again.
The app does not open a second time; nothing happens. The app runs one instance. A second start brings the existing window to the front instead, and if the window was closed to the tray, look for the "LU" icon in the tray (it may sit in the overflow area) and double-click it, or choose "Show" from its menu.
Closing the window did not quit the app. That is by design. The X hides the window to the tray, and after 30 seconds the app also unloads the local models so the graphics card is free again. "Quit" in the tray menu ends the app and its helper programs.
"Could not reach the update server. Check your connection and try again." The check against GitHub failed. It is retried every six hours, or press "Check for updates" under Settings, General, Updates.
"The update could not be downloaded." or "The downloaded update was lost when the app restarted. Download it again." Press "Retry" in the update panel or "Download Update" again. The download starts over.
"The update could not be installed." On Windows, download the current installer from the Releases page and run it over the existing install; your data stays. On Linux, the same sentence used to appear after a password prompt on installs the updater could not write, such as the AUR package. Since 2.6.9 those installs update themselves as described above; if you still see it, download the AppImage from the Releases page and run that.
The .deb refuses to install because of /usr/bin/llama-server. That was version 2.6.6 and older, whose package shipped the engine under the same name as Debian's llama.cpp-tools. Since 2.6.7 the engine is called lu-llama-server and the conflict is gone. Download the current package.
Linux: the window opens but stays empty. See the Wayland callout above. If you have set WEBKIT_DISABLE_DMABUF_RENDERER, WEBKIT_DISABLE_COMPOSITING_MODE or LD_PRELOAD yourself, unset them so the app can apply its defaults. The app also reveals its window after ten seconds at the latest, so wait that long before you decide.
Previous chapter: What it is. Next chapter: First start. Back to the handbook overview.