Installing

🌐 Also available in: Deutsch

Installing (gramps-connect-desktop)

gramps-connect-desktop is the standalone build of Gramps Connect: one downloadable app that bundles the app/ frontend and gramps-web-api's backend together with SQLite, and runs entirely on your own machine. It's the easiest way to try Gramps Connect today, and a real alternative to Gramps Desktop for day-to-day work on your own tree — not a limited preview of anything else.

It's single-user by design: it only listens on 127.0.0.1, so nothing about it is reachable over a network, and it always has exactly one hardcoded login, admin / admin. If you want a whole family logged into one shared tree, or to see the live-collaboration features in action, see Deploying instead — the standalone build has no one else's edits to watch appear.

Every current download lives on the latest release. All of them start with an empty tree — import your own Gramps XML (.gramps) or GEDCOM (.ged) file via the app's own Family Trees → Import... screen once it's running.

First run creates a small data directory in your home folder (.gramps-connect-desktop) holding that tree; later runs reuse it. Delete that folder to reset back to a blank slate. These are unsigned, x86_64-only builds, hence the OS warnings described below — not a sign anything is wrong.

Windows

1. Download gramps-connect-desktop-windows.zip from the latest release and unzip it (right-click → Extract All).
2. Open the extracted folder and double-click gramps-connect-desktop.exe.
3. Windows will likely show a SmartScreen warning ("Windows protected your PC") because this isn't a signed executable. Click More info, then Run anyway.
4. A window opens automatically, running the app. Log in as admin / admin.

macOS (Apple Silicon)

For M1/M2/M3/M4 Macs.

1. Download gramps-connect-desktop-macos-arm64.zip from the latest release and unzip it (double-click, or right-click → Open, depending on your Mac's settings) to get gramps-connect-desktop.app.
2. Double-click gramps-connect-desktop.app. This build is signed with a Developer ID and notarized by Apple, so it should open normally with no Gatekeeper warning at all. If you see one anyway, see Troubleshooting below.
3. A window opens automatically, running the app. Log in as admin / admin.

macOS (Intel)

For older Intel-based Macs (pre-Apple Silicon). Same steps as Apple Silicon above, but download gramps-connect-desktop-macos-intel.zip instead.

Linux (.deb — Debian, Ubuntu, and derivatives)

1. Download the .deb file (gramps-connect-desktop_*_amd64.deb) from the latest release.
2. Install it: sudo apt install ./gramps-connect-desktop_*_amd64.deb (installing from a local file rather than a repo, so apt will likely warn that the package isn't signed — expected, see Troubleshooting).
3. Run gramps-connect-desktop from a terminal, or find "Gramps Connect Desktop" in your applications menu.
4. This opens in its own native window, using GTK3 + WebKit2 already on your system (common on Linux desktops — many apps depend on them already; neither is bundled by this package). If your system doesn't have them, it opens in a browser tab instead (see Troubleshooting). Log in as admin / admin.
5. To uninstall: sudo apt remove gramps-connect-desktop.

Linux (.rpm — Fedora, RHEL, AlmaLinux, and derivatives)

1. Download the .rpm file (gramps-connect-desktop-*.x86_64.rpm) from the latest release.
2. Install it: sudo dnf install ./gramps-connect-desktop-*.x86_64.rpm (on a system without dnf, sudo rpm -i gramps-connect-desktop-*.x86_64.rpm works too, just without automatic dependency resolution). As with the .deb above, installing from a local file means dnf/rpm will likely warn that the package isn't signed — expected.
3. Run gramps-connect-desktop from a terminal, or find "Gramps Connect Desktop" in your applications menu.
4. This opens in its own native window (or falls back to a browser tab) — same as the .deb above. Log in as admin / admin.
5. To uninstall: sudo dnf remove gramps-connect-desktop.

Configuration

gramps-connect-desktop works with no configuration at all. The one optional knob is outbound e-mail: by default, anything that would send mail (password reset, e-mail confirmation, new-user notification — not that there's anyone to notify on a single-user build) just fails with "Connection was refused," since there's no mail server on your machine for it to talk to. To actually send those e-mails, set these environment variables before launching the app:

Variable	Purpose
GRAMPSWEB_EMAIL_HOST	SMTP server hostname
GRAMPSWEB_EMAIL_PORT	SMTP server port (default 465)
GRAMPSWEB_EMAIL_HOST_USER	SMTP login username
GRAMPSWEB_EMAIL_HOST_PASSWORD	SMTP login password
GRAMPSWEB_DEFAULT_FROM_EMAIL	"From" address on sent e-mails
GRAMPSWEB_EMAIL_USE_SSL	true/false — implicit TLS/SSL connection
GRAMPSWEB_EMAIL_USE_STARTTLS	true/false — plain connection upgraded via STARTTLS
GRAMPSWEB_EMAIL_USE_TLS	true/false — older alias; prefer the two above (default true, i.e. implicit TLS)

Only the variables you set take effect; anything left unset falls back to gramps-web-api's own default for that option. For example, to send through Gmail with an app password:

GRAMPSWEB_EMAIL_HOST=smtp.gmail.com \
GRAMPSWEB_EMAIL_PORT=587 \
GRAMPSWEB_EMAIL_HOST_USER=you@gmail.com \
GRAMPSWEB_EMAIL_HOST_PASSWORD=your-app-password \
GRAMPSWEB_EMAIL_USE_STARTTLS=true \
GRAMPSWEB_DEFAULT_FROM_EMAIL=you@gmail.com \
./gramps-connect-desktop

Run from a terminal, --browser skips the native window on macOS/Windows and always opens in your default browser instead — the same fallback Linux always uses (see Architecture), just opted into rather than automatic. Handy if you'd rather use your own browser's devtools/extensions, or want to rule out the native webview when something looks wrong:

./gramps-connect-desktop --browser

Troubleshooting

• Windows SmartScreen ("Windows protected your PC") — expected, since this build isn't code-signed. Click More info → Run anyway.
• macOS Gatekeeper ("cannot be opened because Apple cannot check it for malicious software") — this build is signed with a Developer ID and notarized by Apple, so this shouldn't happen. If it does, first try clearing the quarantine flag from the whole .app at once: xattr -cr gramps-connect-desktop.app (run from Terminal, in the folder you unzipped it into). Please also report it — it likely means the notarization ticket didn't survive being downloaded/unzipped as expected, or the build wasn't notarized correctly.
• apt/dnf warns the .deb/.rpm isn't signed, or skips an OpenPGP check — expected. These packages are built by this repo's own CI, not published to a signed distro repository, so installing them from a local file always looks this way; it doesn't mean anything is wrong.
• dnf: command not found / rpm: command not found — your distro is Debian/Ubuntu-based (or otherwise doesn't ship rpm), so the .rpm package is the wrong download. Grab the .deb file instead and install it with sudo apt install ./gramps-connect-desktop_*_amd64.deb (see the .deb section above).
• No window or browser tab appears on any platform — the app always tries to open one automatically once its server is up; if that somehow fails, open http://127.0.0.1:5050 yourself. If nothing is listening there either, something crashed before reaching that point — check the terminal output (Windows: run gramps-connect-desktop.exe from a cmd/ PowerShell window instead of double-clicking, so you can see it) for an error, and consider opening an issue with that output.
• The app won't start / port already in use — only one instance can run at a time (it's hardcoded to 127.0.0.1:5050). Close any other running copy, or anything else using port 5050, and try again.
• A browser tab opens instead of a native window — the app always tries a native window first and falls back automatically if it can't: WebView2 on Windows (present by default on Windows 10/11) or WKWebView on macOS (always present) couldn't be reached, or on Linux, GTK3 + WebKit2 aren't installed system-wide (install python3-gi, gir1.2-gtk-3.0, and gir1.2-webkit2-4.1, or your distro's equivalents, and relaunch to get a native window instead). The app still works fully in the browser tab either way — this only affects how it's presented, not what it can do.
• Start over from a blank tree — delete the .gramps-connect-desktop folder in your home directory, then relaunch.
• Looking for a real multi-user deployment instead of this single-user local build? See Deploying.

See also FAQ for questions about data safety and how gramps-connect-desktop compares to Gramps Desktop and the server deployment.