Warning
This project is a proof of concept (POC). It is experimental, unstable, and not intended for production use.
This is the v3 branch of Fractal Lite: the same FastAPI + SvelteKit application as the other branches, packaged as a native desktop app with Electron. The Python backend and SvelteKit frontend are bundled into a self-contained binary via PyInstaller, so no Python or Node.js installation is required on the user's machine.
This project contains two main components:
- fractal-lite: A minimalistic implementation of fractal core concepts (datasets, collection, tasks, workflows, projects, history) without need of a database.
- An Electron desktop app that spawns the FastAPI/uvicorn backend as a child process and points a native window at it.
You can either download a pre-built installer or build it yourself.
Pre-built installers for every v3.x.y release are available on the
Releases page.
Download the asset matching your OS:
| OS | Asset |
|---|---|
| Linux (x86_64, Ubuntu 22.04 or newer) | v3.x.y-FractalLite-ubuntu-22.04.AppImage |
| Windows (x86_64) | v3.x.y-FractalLite-windows-2025.exe |
| macOS, Apple Silicon (M1 or newer) | v3.x.y-FractalLite-macos-26.dmg |
| macOS, Intel, macOS 15 | v3.x.y-FractalLite-macos-15-intel.dmg |
| macOS, Intel, macOS 26 or newer | v3.x.y-FractalLite-macos-26-intel.dmg |
The build produces an installer for the OS (and CPU architecture) you run it on. Cross-compiling is not supported.
Requirements
- Node.js 22+ and npm
- Python 3.12+, available as
python3 - git
- bash. On Windows, use Git Bash and make sure
python3 --versionprints 3.12 or newer there.
Steps
All the Electron/npm tooling lives in the electron/ subfolder. From the root of
the cloned repository run:
cd electron
npm install
npm run full-buildnpm run full-build builds the SvelteKit frontend, packages the Python backend with
PyInstaller, and packages everything with electron-builder. The first run takes a while.
The installer is written to electron/dist-electron/:
| OS | Output |
|---|---|
| Linux | FractalLite-<version>-linux-x86_64.AppImage |
| Windows | FractalLite-<version>-win-x64.exe |
| macOS | FractalLite-<version>-mac-<arch>.dmg |
None of the installers are code-signed, so each OS asks for confirmation the first time you launch the app.
Make the AppImage executable, then launch it:
chmod +x <file>.AppImage
./<file>.AppImageIf it fails with an error about FUSE (dlopen(): error loading libfuse.so.2),
install FUSE 2:
sudo apt install libfuse2 # Ubuntu 22.04
sudo apt install libfuse2t64 # Ubuntu 24.04 or newerThe app isn't signed with an Apple Developer certificate, so Gatekeeper blocks it on the first launch. You only need to approve it once.
-
Install. Double-click the downloaded
.dmgfile. In the window that opens, drag the Fractal Lite icon onto the Applications folder.
-
First launch. Open Fractal Lite from Applications. macOS refuses to open it with a "Fractal Lite" Not Opened dialog, saying Apple could not verify that it is free of malware. Click Done. Do not click Move to Trash.
-
Allow the app. Open System Settings → Privacy & Security and scroll down to the Security section. Next to the message "Fractal Lite" was blocked to protect your Mac, click Open Anyway. macOS may ask for your password or Touch ID.
-
Confirm. A last dialog asks Open "Fractal Lite"?. Click Open Anyway. The app starts, and from then on it opens normally.
The screenshots come from a Mac set to Italian. The button labels in English are the ones in bold above.
If macOS says the app "is damaged and can't be opened", or that it contains malware and moves it to the Trash, re-download it, install it again, then re-sign it locally and remove the quarantine attribute:
codesign --force --deep --sign - "/Applications/Fractal Lite.app"
xattr -cr "/Applications/Fractal Lite.app"- Run the installer (
.exe). Windows Defender SmartScreen may warn about an unknown publisher: click More info, then Run anyway. - The installer installs the app for the current user and starts it.
- Afterwards, launch Fractal Lite from the Start menu or the desktop shortcut.
When you launch Fractal Lite, Electron starts the Python server (fractal-app-lite) in the background, waits for it to be ready, then opens a window pointing at it. The UI and application logic live entirely inside the Python/SvelteKit bundle — Electron is only the container.
Electron (main process)
│
├─ spawns ──► fractal-app-lite (Python / uvicorn / FastAPI)
│ │
│ ├─ GET /api/* → Python handlers
│ └─ GET /* → static SvelteKit frontend
│
└─ opens ───► BrowserWindow → http://127.0.0.1:<random port>
The port is chosen randomly at startup, so there are no conflicts with other services.
See electron/documentation.md for the full build/packaging pipeline and electron/CLAUDE.md for an architecture overview.
Unless noted otherwise, run these from the electron/ folder, after npm install.
npm run build-components # build frontend + Python backend (needed at least once)
npm run devnpm run dev compiles the TypeScript with hot-reload and launches Electron directly
from the source tree.
To rebuild only one part (the backend build bakes the frontend into the PyInstaller bundle, so after a frontend change you need both):
npm run build-frontend # rebuild only the SvelteKit frontend (scripts/build-frontend.sh)
npm run build-backend # rebuild only the Python binary (scripts/build-backend.sh)npm run typecheck # type-check the main process TypeScript (no output = clean)
npm run build # compile TypeScript only → out/The Python backend can still be run standalone (without Electron) via pixi, e.g. for iterating on the API without rebuilding the desktop shell. Run this from the repo root (not electron/):
pixi run serve # runs uvicorn directly, serving the built frontend if presentTo open the app in its own desktop window (via pywebview) instead of a browser:
pixi run appThe app task lives in the optional gui environment, and pixi picks that environment automatically, so there is no need to add -e gui. The first run takes a while, because pixi installs pywebview (plus Qt on Linux). The Electron app does not use any of this.
Run these from the repo root (not electron/):
pixi run -e dev test # full test suite
pixi run -e dev test-fast # skip slow e2e testsFrom the repo root:
pixi run -e dev lintPush a v3.x.y tag:
git tag v3.1.0
git push --tagsThis triggers .github/workflows/release.yml, which builds installers for Linux, Windows and macOS (Intel and Apple Silicon) and uploads them to a GitHub Release. To trigger a build without creating a release (useful for testing), run the workflow manually from the Actions tab — the results are uploaded as workflow artifacts (kept for 7 days) instead.
- No database — fractal-app-lite uses in-memory state and file-based project storage.
- macOS code-signing — for public distribution, uncomment the
hardenedRuntime/entitlementslines inelectron/electron-builder.ymland provide an Apple Developer certificate. - macOS notarization — requires an Apple Developer account and the
CSC_LINK/APPLE_IDenvironment variables set when runningelectron-builder. fractal-web-clone— thefractal-web-clone/directory at the repo root is created byscripts/build-frontend.sh(not a git submodule). Delete it and re-run the build script to refresh it.
BSD 3-Clause — see LICENSE.