genealogy-research-workbench 0.5.0

Turn a GEDCOM or OneTree export into a searchable family-history website.

· Releases · MIT

Get started · Your first site · Take a look · Import formats · Privacy · Developer guide

Bring your own family tree. Build a site with people pages, an interactive whole tree, family branches, timelines, places, sources, research studies, a findings log, comparisons and connection paths. Keep the underlying research in portable, source-aware records that distinguish an imported assertion from an assessed conclusion.

Run everything on your own computer. The toolkit has no runtime dependencies, makes no network requests during import or builds, and generates ordinary HTML, CSS, JavaScript and data files. You choose whether and where to publish them.

What you can build

Explore the whole tree Pan and zoom through every public person, focus on a family or browse branch cards. Uncertain links are dashed, and every link keeps its recorded label.	Find the person behind a name Search names, relatives, events and places; filter by surname, year and evidence; sort and paginate.
Read a family at a glance Each dossier lists parents, partners with their marriages, children and siblings. Step, adoptive and other recorded roles stay visible. When more parents are recorded than one person can have by birth, the dossier flags them as competing parent records.	Follow lives through time and place Browse a filterable event timeline and an offline coordinate map. Places without coordinates stay in the place list; the toolkit never guesses their positions.
Write up what you found Studies set out why a question was investigated, what the records show and the current conclusion. They link to the people and records they concern, and those pages link back. A dated Latest findings log and an Atom feed follow your conclusions over time.	See the families at a glance Surname groups show their recorded years, places and earliest people. Connected groups show who is joined by recorded relationships, with links into the catalogue and the family tree.
Keep the evidence in view Sources, claims, evidence assessments, hypotheses, questions and findings stay distinct, with outstanding work listed first.	Say exactly how sure you are One vocabulary covers every page. An imported link reads "Unassessed tree link", and a tree's own mark reads "tree-marked uncertain". Every label links to a reader's guide.

The screenshots use the fully fictional Alderwick demo, captured on 19 October 2026 at 1440 × 1000. They contain no real family data. Core people, source, and research content remains readable with JavaScript disabled; interactive tools use local JavaScript.

Get started

You need Python 3.11 or later. Install the toolkit from PyPI:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install genealogy-research-workbench

On Windows, activate with .venv\Scripts\activate instead. No Node.js, database, account, browser automation, or API key is required to use the toolkit. To work on the toolkit itself, or to run the fictional demo, clone this repository and see installation. New here? Your first site walks through every step.

Choose a file in your browser

genealogy --project my-workspace serve

Open the printed http://127.0.0.1:8000/ URL. Choose your .ged, .gedcom, GEDCOM 7 .gdz or OneTree .json file, enter a public project title, and create a preview. The file is sent only to the local server on your computer.

Publication controls are explicit: permit reviewed basic deceased-person facts, and optionally reviewed source bibliography and citation locators. Living, unknown-status, explicitly private, restricted, and licensed material stays protected. Imported notes, quotations, and transcriptions are retained privately. See the exact publication rules.

The upload screen saves each import as its own project under my-workspace/private/previews/. Its preview link works while that server runs. Keep the saved project to continue researching or build its dist/ folder for hosting. This command is a local desktop tool, not a public upload service.

Or use the command line

genealogy init my-family --name "Our family history"
genealogy --project my-family import /path/to/family.ged \
  --publish-deceased --publish-reviewed-sources
genealogy --project my-family validate
genealogy --project my-family build
python -m http.server 8000 --bind 127.0.0.1 --directory my-family/dist

Open localhost:8000. For OneTree, use the same command with a JSON export:

genealogy --project my-family import /path/to/one-tree.json --publish-deceased

Got a newer export of the same tree? import FILE --update refreshes the imported records and keeps the research you added: findings, questions, sources and notes. It stops, changing nothing, if that research would point at someone the new export no longer contains. --replace starts again from the new file. Both keep a private backup of the previous case first. An identical import with the same review options does nothing. Omitting publication options keeps the imported records private, so the public site can be empty. Your original input is preserved privately and never modified.

Everything the importer does not interpret is counted in the import report and kept in the private original. See import formats.

Try it before importing your family

From the toolkit checkout:

genealogy --project examples/demo build
python -m http.server 8000 --bind 127.0.0.1 --directory examples/demo/dist

The demo has 42 invented people, four generations, sources, uncertainty, and research questions. The matching GEDCOM and OneTree files let you exercise the complete import workflow.

How much of a research site can an export recreate?

An export supplies recorded tree assertions. It cannot manufacture missing sources, prove parentage, recover photographs, or infer DNA results. OneTree biography text is retained privately; arbitrary WikiTree markup is not converted into independently verified citations. Supported formats and limitations describe exactly what is imported.

This toolkit grew out of the Glasgow Surname Project. The reusable package includes the research model, adapters, local upload workflow, and general website. Glasgow’s historical research, surname rules, private records, custom editorial pages, and DNA studies remain in that project.

Continue the research

genealogy --project my-family search "harbour"
genealogy --project my-family record list --kind Person
genealogy --project my-family record show gedcom:person:I1
genealogy --project my-family report --format markdown --output research-brief.md
genealogy --project my-family export json --output dist/research.json
genealogy --project my-family export csv --output dist/research.csv
genealogy --project my-family export gedcom --output dist/public-tree.ged
genealogy --project my-family bundle --output private/research-bundle
genealogy --project my-family bundle --output private/research-bundle --verify
genealogy --project my-family check-links

Typed records can be added with record add TYPE --input record.json. Findings can link related records and evidence and carry the date they were reached. Studies hold the written account. Research recipes cover citations, confidence, studies, place precision, public review and maintaining a case. A complete research bundle includes protected content and stays private, unlike a filtered website or public export.

A portable project

my-family/
├── genealogy.toml          Project name, paths, views and privacy settings
├── cases/                  Private typed research cases
├── private/imports/        Original exports and bounded import reports
└── dist/                   Generated, privacy-filtered website and downloads

All generated site links are relative, so the site works under a subdirectory and can be hosted on an ordinary static server. It needs no external scripts, maps, fonts, or analytics. Build into a dedicated output folder: generated files are replaced on rebuild, and obsolete generated dossiers are removed. Files outside the generated manifest are preserved.

Documentation and development

python -m pip install -e '.[dev]'
make check
python -m build

Browser checks are optional: install .[browser], run python -m playwright install chromium, then make browser-check. Tests and demos use fictional records only.

Licensed under MIT. The software license does not grant rights to records, photographs, or other material you import.