GEDCOM Files Explained

GEDCOM stands for GEnealogical Data COMmunication. It's a plain-text file format, usually ending in .ged, designed to hold an entire family tree. Every person, every birth and death date, every marriage, every parent-child and spousal relationship, in a form that any genealogy program can read. FamilySearch publishes the specification, and the copyright line on the current document runs from 1984 to today.

Say you spent three years building a tree on one genealogy platform. If that platform raises its prices, shuts down, or simply isn't the right tool anymore, the GEDCOM export is your exit door. What comes through that door is less than you think.

What the .ged extension means

The specification is direct about it: a file containing a GEDCOM data stream “should use the filename extension .ged.” A GED file and a GEDCOM file are the same thing. The extension carries no version information, so a .ged written in 1999 and one written last week look identical from the outside. There is no viewer to install either. Open it in Notepad, TextEdit or any code editor and you will see the whole file.

GEDZIP, and the .gdz extension

GEDCOM 7 added a second container for what the bare text file never handled: a tree plus its actual photographs and documents. A GEDZIP file is an ordinary zip archive, standardized by ISO/IEC 21320-1:2015, holding one entry named gedcom.ged and one entry for each file that entry references. Saved to disk it takes the extension .gdz. Version 7.0 was the first release to define it, so 5.5.1 has no equivalent.

What’s actually inside

Every line follows one shape, in the 5.5.1 spec’s own words: “A line always contains a hierarchical level number, a tag, and an optional value.” Nothing is indented and nothing is nested in brackets. The level number alone builds the hierarchy, because a subordinate line carries a higher number than the line it belongs to.

The second idea makes it a tree rather than a list. Identifiers wrapped in at-signs, like @I1@, are cross-references. A person points at a family record and the family record points back, so every relationship is stored from both ends.

Here is a complete file using every tag in that table. The names are invented. It was checked with js-gedcom against FamilySearch’s own machine-readable validation registry: zero errors, zero warnings.

0 HEAD
1 GEDC
2 VERS 7.0
1 SOUR FamilyRootsGuideExample
2 NAME Family Roots guide example
1 DATE 26 JUL 2026
0 @I1@ INDI
1 NAME Bartholomew /Example/
2 GIVN Bartholomew
2 SURN Example
1 SEX M
1 BIRT
2 DATE 12 MAR 1888
2 PLAC Abilene, Taylor, Texas, United States of America
3 FORM City, County, State, Country
1 DEAT
2 DATE 4 NOV 1951
2 PLAC Abilene, Taylor, Texas, United States of America
1 FAMS @F1@
1 SOUR @S1@
2 PAGE Taylor County, Texas, entry for Bartholomew Example
0 @I2@ INDI
1 NAME Amelia /Placeholder/
1 SEX F
1 BIRT
2 DATE ABT 1890
1 FAMS @F1@
0 @I3@ INDI
1 NAME Clara /Example/
1 SEX F
1 BIRT
2 DATE 21 JUN 1915
1 FAMC @F1@
0 @F1@ FAM
1 HUSB @I1@
1 WIFE @I2@
1 CHIL @I3@
1 MARR
2 DATE 9 SEP 1911
2 PLAC Abilene, Taylor, Texas, United States of America
0 @S1@ SOUR
1 TITL 1900 United States Federal Census
0 TRLR

Reading it from the top:

• 0 HEAD opens the header, and 2 VERS 7.0 declares which version of the format the file follows.
• 0 @I1@ INDI opens a person under the identifier @I1@. Everything at level 1 below it belongs to them until the next level-0 line.
• 1 NAME Bartholomew /Example/ puts the surname between slashes, which is how a program knows the family name without guessing.
• 1 BIRT carries no value of its own. 2 DATE and 2 PLAC underneath it describe the event.
• 1 FAMS @F1@ makes this person a spouse in family @F1@, and 0 @F1@ FAM lists HUSB, WIFE and CHIL pointing back. A child’s record uses FAMC.
• 1 SOUR @S1@ attaches a citation, 2 PAGE says where in that source it sits, and 0 TRLR ends the file.

One thing a validator will not do: it checks that a date is written correctly, not that it could have happened. A file claiming 31 February 1888 passes clean.

Moving your tree between platforms

Ancestry

1. From any page, click the Trees tab and select a tree.
2. In the toolbar on the left, click More (three dots) and select Tree Settings.
3. Under Manage your tree, click Export tree.
4. Click Export. The button spins and reads Generating a GEDCOM file.
5. When it stops, click Download Your GEDCOM File.

Only the tree owner can export, and no paid membership is needed to do it. The file arrives inside a zip. Uploads back to Ancestry must be under 500MB.

MyHeritage

1. Log in to your family site.
2. Hover over Family tree and click Manage Trees.
3. Click Export to GEDCOM next to the tree you want.
4. Choose whether to include photos, then click Begin the export.

That photo checkbox does not do what it sounds like. MyHeritage says the file “doesn’t include the actual photos but it may contain the links to the photos’ original location.” You are exporting addresses, not images.

Findmypast

Open the My Family Tree link at the top of the site and view all trees. Icons sit to the right of each tree name. Hover to find the one labelled Export tree and click it. The help article offers no format choice and says nothing about media.

FamilySearch, which is its own case

FamilySearch publishes the specification, and its shared Family Tree has no conventional export. Help centre articles dated June 2025 say you cannot download GEDCOM files from Family Tree and recommend third-party software instead. Separately, FamilySearch runs an export tool that hands you eight generations, starting with you, as a GEDCOM 7 file with no photos. That file is too new for one of its own products: the Genealogies upload accepts “all versions of GEDCOM up to and including GEDCOM 5.5.1.”

What doesn’t survive the trip

Almost every loss below traces to one word. The specification says “recommended” where readers assume it says “required.” Programs are recommended to let you filter private data on export, and recommended not to invent their own tags. Nothing obliges a receiving program to keep a tag it did not write. The format is portable to the degree the program on the other end chose to cooperate.

Photos and media

The .ged file you are handed does not contain an image. Version 5.5 allowed media to be embedded and 5.5.1 eliminated the tag that carried it, so every file produced in the twenty-five years since holds paths and links instead. Those break the moment the file leaves the machine or account that wrote it. Ancestry states that photos and media are not included. MyHeritage exports links. The FamilySearch tool says it does not include photo files.

Source citations

This is the loss that hurts, because citations took the longest to build. FamilySearch says it about its own product in one sentence: “The sources, notes, and media in your GEDCOM file cannot be transferred to Family Tree.” Custom events like a bar mitzvah or an immigration are not displayed either. 5.5.1 admitted the same pattern about its optional name parts: anyone using them “should assume that few systems will process them.”

Notes and long text

Long text gets split across physical lines. 5.5.1 used CONT for a real line break and CONC for a continuation with none, and warned that a line broken at a space must carry the space over. Writers that get that wrong are why words come back jammed together. GEDCOM 7 deleted CONC and added formatting through a MIME type. Older software has no MIME, so anything formatted that way arrives as raw markup or not at all.

Vendor and custom fields

Tags beginning with an underscore, like _UID or _APID, are how each platform stores what the standard does not cover. They are legal, and their meaning is private. 5.5.1 says a user-defined tag “should only be interpreted in the context of the sending system.” Neither version obliges the receiving program to keep a tag it did not write, and 5.5.1 designed readers to skip what they did not recognise. That is how a decade of custom fields evaporates in one import.

Accented and non-Latin names

This is the mojibake section. 5.5.1’s preferred character set was ANSEL, a library cataloguing encoding from the 1980s, and it required every character above 0x7F to be converted to it. Whether an accented name survives depends on the reading program honouring the CHAR line. Writer declares ANSEL, reader assumes UTF-8, and there are your garbled vowels. GEDCOM 7 removed the choice and uses UTF-8 only.

Living people

Living is a platform concept more than a file concept. The format has a restriction tag, RESN, and the spec then says its own PRIVACYvalue “is known to admit multiple interpretations, so use of the PRIVACY restriction notice is not recommended.” The tag requests filtering. It does not perform it.

Neither Ancestry nor MyHeritage documents what its export does with living relatives. What Ancestry does document is the receiving end: when a tree arrives with no living or deceased status attached, which it says happens, Ancestry looks for death information, then assumes anyone under 100 is living, then checks the ages of close relatives. Your privacy settings do not travel. They get re-derived by whoever receives the file.

Versions: 5.5.1 and what came after

The current specification is FamilySearch GEDCOM 7.0.18, published 17 February 2026. The 7.0 line was released in 2021 and the point releases since are errata rather than new formats. The version you will actually meet is 5.5.1. It was drafted in 1999, circulated for two decades, and was only formally published in 2019, which is why you will see both years quoted as its date. It has never been deprecated, and it is what most consumer platforms still write and read.

The two are not compatible in the direction that matters. Take a 5.5.1 file that is entirely valid, correct line grammar and every cross-reference resolving, and run it through a GEDCOM 7 validator:

ERRORS (4):
  - Prohibited substructure of .../v7/GEDC: FORM
  - FORM cannot be used as substructure of .../v7/GEDC
  - Prohibited substructure of .../v7/HEAD: CHAR
  - CHAR cannot be used as substructure of .../v7/HEAD
WARNINGS:
  - Expected HEAD.GEDC.VERS 7.0, not 5.5.1

It fails on CHAR, the character-set line 5.5.1 required every file to carry, and on GEDC.FORM, which 5.5.1 also required. The two lines a conforming 5.5.1 writer had to emit are two lines GEDCOM 7 prohibits. FamilySearch says as much in its own export instructions: if you get an error importing the file, the site or app may not support GEDCOM 7. When an export offers you a version choice, 5.5.1 is the safer answer unless you know the receiver reads 7.

Common questions