Claude generated revision of the 6.0 documentation Generated-by: Claude Sonnet 4.6 (Anthropic) Prompts: Gap analysis of Gramps 6.0 CLI documentation vs. source capabilities, followed by MediaWiki markup regeneration integrating revision suggestions. Guidelines: https://www.gramps-project.org/wiki/index.php/Howto:_Contribute_to_Gramps#AI_generated_code Co-authored-by: Claude Sonnet 4.6 <[email protected]>

Gramps 6.0 Wiki Manual - Command Line

From Gramps

This appendix provides the reference to the command line capabilities available when launching Gramps (for desktops) from the command line.

For help on Gramps Web

See Managing users on the command line on the User System page of the Gramps Web documentation.

Start Gramps through the Command Line

Normally Gramps is started through the graphical user interface (GUI) on your platform.

It is also possible to start Gramps using a command line interface (CLI). CLI use can

produce reports that are not available via the GUI,
create reports, do conversions etc. without opening a window and
can provide extra information in the event of problems.

This section of the user manual describes how to start Gramps through the CLI, and the features that are available.

The way you start Gramps through the CLI depends on the operating system you are using.

For simplicity of description, the examples of use below are written from the point of view of running Gramps on Linux. The examples would need to be changed for other platforms.

Linux

Linux platform is the main officially supported platform. (Other platforms are community supported.) This is because Gramps developers design, code, use and test the source code on that platform. So diagnosing and fixing any problems that arise (whether due to upgrades or other causes) is done using Linux tools.

Assuming you have used the standard Package Manager (either through a CLI or a GUI) for your Linux distribution, you start Gramps through the CLI by typing:

gramps

If you have done a "build from source", navigate to where you installed the application. (That folder will include the Gramps.py file.) Type:

python3 Gramps.py

MS Windows

MS Windows is an officially supported platform. If you install the Windows AIO bundle, then this will place an icon on the desktop as well as a menu item in the 'Start' menu. However, the Gramps installation directory is not added to the system path and to run gramps via CLI, we need to know the path to that directory.

To find the installation folder, refer to the AIO bundle's installation folder section.

To find the path using a shortcut icon instead:

Right-click on the GrampsAIO64 6.0.8-console application, or the corresponding item in the Start menu.
Note down the file location (its 'Start in' directory).
Select the full path and copy (Template:Key+Template:Key) it.

To run Gramps from the command line, you'll need to start a console window:

From the Start menu, start cmd.exe.
Change directory to the installation directory you located.
Type in or paste the path, surrounding it in quotes if there are spaces.
Press Template:Key.

For example, this might be:

cd "C:\Program Files\GrampsAIO64-6.0.8"
gramps

You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would append -L:

cd "C:\Program Files\GrampsAIO64-6.0.8"
gramps -L

Advanced: To be able to start Gramps from any directory.

You can add to the existing PATH environment variable on Windows by opening the Windows Start menu, searching for "env", and choosing Edit the system environment variables. Select Environment Variables…, then in the System Variables section edit the Path row and add the Gramps install path (e.g. C:\Program Files\GrampsAIO64-6.0.8). Accept and restart the computer. For each new release of Gramps you will need to adjust the path as it contains the version number.

macOS

macOS is a community supported platform. If you download the macOS disk image (.dmg), then you simply drag the application to your application folder (or anywhere else you want to store it) and start Gramps by double clicking on the application in the normal way. The Homebrew package manager also allows for installation of the application in the usual Applications folder.

To run from the command line, you'll need to start Terminal, found in the Utilities folder of the main Applications folder (/Applications/Utilities). Once you have a terminal window open, at the prompt type:

/path/to/Gramps.app/Contents/MacOS/Gramps

If you installed Gramps in Applications along with most of your other apps, as suggested above, that would be:

/Applications/Gramps.app/Contents/MacOS/Gramps

You may use any of the command-line options along with this. For example, to get a detailed listing of all of the Family Tree databases in your default Family Tree folder, you would use:

/Applications/Gramps.app/Contents/MacOS/Gramps -L

There are other ways to install Gramps for macOS, but these are much more complicated and are not covered here.

Python options

In the examples of different platforms above, and also in commands in various files you may see some options after the 'python' command, for example -EO in:

python3 -EO ..\share\gramps\gramps.py -L

It is important to distinguish between the python options (-EO) and the Gramps options (-L).

The python options that you may come across are:

-E Ignore all PYTHON* environment variables, e.g. PYTHONPATH and PYTHONHOME, that might be set.
-O Turn on basic optimizations. This changes the filename extension for compiled (bytecode) files from .pyc to .pyo. See also PYTHONOPTIMIZE.

The -O optimise flag has a number of effects in Gramps:

If it is not turned on, an additional Debug entry appears in the Tools menu.
If it is not turned on, info logging messages are output.
If it is not turned on, debug statements may be activated.
If it is not turned on, additional features are available in the Plugin Manager.

The Gramps options are described below.

Available Gramps options

This section provides the reference list of all command line options available in Gramps. If you want to know more than just a list of options, see next sections: Operation and Examples.

Help options

The summary below is printed by:

gramps --help

or

gramps -h

Usage: gramps [OPTION...]
  --load-modules=MODULE1,MODULE2,...  Dynamic modules to load

Help options
  -?, --help              Show this help message
      --usage             Display brief usage message

Application options
  -O, --open=FAMILY_TREE          Open Family Tree
  -U, --username=USERNAME         Database username
  -P, --password=PASSWORD         Database password
  -C, --create=FAMILY_TREE        Create on open if new Family Tree
  -i, --import=FILENAME           Import file
  -e, --export=FILENAME           Export file
  -r, --remove=FAMILY_TREE_PATTERN  Remove matching Family Tree(s) (use regular expressions)
  -f, --format=FORMAT             Specify Family Tree format
  -a, --action=ACTION             Specify action
  -p, --options=OPTIONS_STRING    Specify options
  -d, --debug=LOGGER_NAME         Enable debug logs
  -l [FAMILY_TREE_PATTERN...]     List Family Trees
  -L [FAMILY_TREE_PATTERN...]     List Family Trees in Detail
  -t [FAMILY_TREE_PATTERN...]     List Family Trees, tab delimited
  -u, --force-unlock              Force unlock of Family Tree
  -s, --show                      Show config settings
  -c, --config=[config.setting[:value]]  Set config setting(s) and start Gramps
  -y, --yes                       Don't ask to confirm dangerous actions (non-GUI mode only)
  -q, --quiet                     Suppress progress indication output (non-GUI mode only)
  -v, --version                   Show versions
  -S, --safe                      Start Gramps in 'Safe mode'
                                    (temporarily use default settings)
  -D, --default=[APXFE]           Reset settings to default;
                                    A - addons are cleared
                                    P - Preferences to default
                                    X - Books are cleared, reports and tool settings to default
                                    F - filters are cleared
                                    E - Everything is set to default or cleared

Usage message

The usage message is as follows:

gramps --usage

Example of usage of Gramps command line interface

1. To import four databases (whose formats can be determined from their names)
   and then check the resulting database for errors, one may type:
   gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a tool -p name=check.

2. To explicitly specify the formats in the above example, append filenames with appropriate -f options:
   gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps -i file4.wft -f wft -a tool -p name=check.

3. To record the database resulting from all imports, supply -e flag
   (use -f if the filename does not allow Gramps to guess the format):
   gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg

4. To save any error messages of the above example into files outfile and errfile, run:
   gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile

5. To import three databases and start interactive Gramps session with the result:
   gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps

6. To open a database and, based on that data, generate timeline report in PDF format
   putting the output into the my_timeline.pdf file:
   gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf

7. To generate a summary of a database:
   gramps -O 'Family Tree 1' -a report -p name=summary

8. Listing report options
   Use the name=timeline,show=all to find out about all available options for the timeline report.
   To find out details of a particular option, use show=option_name, e.g. name=timeline,show=off string.
   To learn about available report names, use name=show string.

9. To convert a Family Tree on the fly to a .gramps xml file:
   gramps -O 'Family Tree 1' -e output.gramps -f gramps

10. To generate a web site into an other locale (in german):
    LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de

11. Finally, to start normal interactive session type:
    gramps

Note

These examples are for bash shell. Syntax may be different for other shells and for Windows.

List options

Print a list of known family trees.

Sparse

-l, List Family Trees

gramps -l

List of known Family Trees in your database path
/home/<~username>/.gramps/grampsdb/5a46c1c3 with name "Example Family Tree"

Detailed

-L, List Family Trees in Detail

gramps -L

Gramps Family Trees:
Family Tree "Example Family Tree":
  Database: SQLite
  Database module location: C:\Program Files\GrampsAIO64-6.0.3\lib\library.zip\sqlite3\__init__.pyc
  Database version: 3.50.1
  Last accessed: 03/08/2025 15:42:22
  Locked?: False
  Number of citations: 2854
  Number of events: 3436
  Number of families: 766
  Number of media: 7
  Number of notes: 19
  Number of people: 2165
  Number of places: 1296
  Number of repositories: 3
  Number of sources: 4
  Number of tags: 2
  Path: C:\Users\<~username>\AppData\Roaming\gramps\grampsdb\687d8278
  Schema version: 21.0.0

Note

Tab delimited

-t, List Family Trees tab delimited

gramps -t
gramps -t "Example6_0"

Version options

-v or --version prints version of Gramps and dependencies, information about environment settings and python and system paths.

gramps -v

Gramps Settings:
----------------
  gramps   : AIO64-6.0.3--1
  o.s.     : Windows
Required:
---------
  Python   : 3.12.11
  Gtk++    : 3.24.49
  pygobject: 3.52.3
  Cairo    : 1.18.4
  pycairo  : 1.28.0
  Pango    : 1.56.3
  PangoCairo: 1.0
  orjson   : 3.10.18
Recommended:
------------
  osmgpsmap: 1.0
  Graphviz : 12.2
  Ghostscr.: 10.05.1
  ICU      : 3.12.10
  PyICU    : not found
Optional:
---------
  Gspell   : 1
  RCS      : not found
  PILLOW   : 11.2.1
  GExiv2   : 0.10
  Exiv2 lib.: not found because exiv2 is not installed
  geocodeglib: 1.0
Environment settings:
---------------------
  LANG         : en_GB.UTF-8
  LANGUAGE     : en_GB
  GRAMPSI18N   : not set
  GRAMPSHOME   : not set
  GRAMPSDIR    : not set
  GRAMPS_RESOURCES : C:\Program Files\GrampsAIO64-6.0.3\share

Format options

The format of any file destined for opening, importing, or exporting can be specified with the

--format=FORMAT

or

-f FORMAT

option. The acceptable FORMAT values are listed below.

Full family tree support

These formats contain all your data that is present in a family tree.

gramps - Gramps XML format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .gramps
gpkg - Gramps package XML format: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gpkg. This creates a zip package with your data as xml, and all your media files included
grdb - pre Gramps 3.x database: This format is available for import to support the old file format of Gramps. Everything in the grdb file is imported. When not specified, it can be guessed if the filename ends with .grdb
burn - GNOME iso burning: export, only available on GNOME where burn protocol exists

Reduced family tree support

These formats contain most, but not all data that can be created in Gramps.

ged - GEDCOM format: This format is available for import, and export. When not specified, it can be guessed if the filename ends with .ged
gw - GeneWeb file: This format is available for import and export. When not specified, it can be guessed if the filename ends with .gw

Subset of your data

These formats contain a specific subset of your data.

csv - Comma Separated Value: This format is available for import and export. Import must use values created by the export function. Only a part of your data is contained in the output. See the CSV export format section below for details of what is and is not exported.
vcf - VCard 3.0 format: import and export
vcs - VCalendar format: export
def - old Pro-Gen format: import
wft - Web Family Tree: This format is available for export only. When not specified, it can be guessed if the filename ends with .wft

Opening options

You can open a family tree, or you can open a file by importing it in an empty family tree.

To let Gramps handle this automatically, just supply the family tree or filename you want to open:

python gramps.py 'My Fam Tree'
python gramps.py JohnDoe.ged

The first opens a family tree, the second imports a GEDCOM into an empty family tree.

Additionally, you can pass Gramps the name of the family tree to be opened, using the -O flag:

python gramps.py 'Family Tree 1'
python gramps.py /home/cristina/.gramps/grampsdb/47320f3d
python gramps.py -O 'Family Tree 1'
python gramps.py -O /home/cristina/.gramps/grampsdb/47320f3d

Warning

If no option flag is given and just a name is typed, Gramps will ignore the rest of the command line arguments. Use the -O flag to open, -i to import, and do something with the data.

Note

Only family trees can be opened directly. For other formats, you will need to use the import option which will set up the empty database and then import data into it. Only a single family tree can be opened. If you need to combine data from several sources, you will need to use the import option.

Import options

The files destined for import can be specified with the -i filename or --import=filename option. The format can be specified with the -f format or --format=format option, immediately following the filename. If not specified, the guess will be attempted based on the filename.

Example:

python gramps.py -i 'Family Tree 1' -i 'Family Tree 2'
python gramps.py -i test.grdb -i data.gramps

Tip

More than one file can be imported in one command. If this is the case, Gramps will incorporate the data from the next file into the database available at the moment. When more than one input file is given, each has to be preceded by -i flag. The files are imported in the specified order, i.e. -i file1 -i file2 and -i file2 -i file1 might produce different Gramps IDs in the resulting database.

Export options

The files destined for export can be specified with the -e filename or --export=filename option. The format can be specified with the -f option immediately following the filename. If not specified, the guess will be attempted based on the filename. For iso format, the filename is actually the name of directory the Gramps database will be written into. For gramps-xml, gpkg, gedcom, wft, geneweb, and gramps-pkg, the filename is the name of the resulting file.

-e, export a family tree in required format. It is not possible to export to a family tree.

Example:

python gramps.py -i 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps

Note that the above does not change 'Family Tree 1' as everything happens via a temporary database, whereas:

python gramps.py -O 'Family Tree 1' -i test.grdb -f grdb -e mergedDB.gramps

will import test.grdb into Family Tree 1, and then export to a file.

Exporting more files

More than one file can be exported in one command. If this is the case, Gramps will attempt to write several files using the data from the database available at the moment. When more than one output file is given, each has to be preceded by -e flag. The files are written one by one, in the specified order.

For example, to export simultaneously to both Gramps XML (for backup) and GEDCOM (for sharing):

gramps -O "Family Tree 1" -e backup.gramps -f gramps -e share.ged -f ged

Export filters and privacy proxies

When exporting, Gramps applies a layered proxy system to control exactly which records and which details are included in the output. These proxies are available for all export formats that support them (Gramps XML, GEDCOM, GeneWeb, Web Family Tree, CSV, and the Gramps package format).

There are five proxies, each independently enabled or disabled:

Proxy name	Config key token	Purpose
Privacy	`privacy`	Strips all records and fields marked as private
Living	`living`	Restricts or removes data about people who are probably still alive
Person filter	`person`	Limits the export to people matched by a named custom filter
Note filter	`note`	Limits exported notes using a named custom filter
Reference filter	`reference`	Excludes records that are not linked to any person selected by the person filter

The proxies are configured through the export.proxy-order configuration setting (visible in gramps --show output), and through additional settings for the living proxy mode and the named filters. Each proxy has an enable flag — 0 means disabled, 1 means enabled.

You can view the current export proxy configuration with:

gramps --show

Look for the line:

export.proxy-order=[['privacy', 0], ['living', 0], ['person', 0], ['note', 0], ['reference', 0]]

Privacy proxy

When enabled, the privacy proxy removes any person, family, event, source, citation, place, repository, note, or media object that has been marked private in the database. It also removes private fields within records that are not themselves entirely private.

Enable the privacy proxy before exporting:

gramps -c export.proxy-order:"[['privacy',1],['living',0],['person',0],['note',0],['reference',0]]" \
       -O "Family Tree 1" -e public.ged -f ged

Living-person proxy

When enabled, the living-person proxy applies a restriction to records for people who are probably still alive (determined by the Gramps Probably Alive algorithm).

The living proxy operates in one of four modes, controlled by the export.living-people configuration setting:

Mode value	Behaviour
`0`	Include all selected people without restriction (proxy has no effect even when enabled)
`1`	Replace the given name(s) of living people with a placeholder
`2`	Replace all name components except the surname with a placeholder
`3`	Exclude living people entirely from the export

Example — export a GEDCOM that omits living people entirely:

gramps -c export.proxy-order:"[['privacy',0],['living',1],['person',0],['note',0],['reference',0]]" \
       -c export.living-people:3 \
       -O "Family Tree 1" -e no_living.ged -f ged

Person filter proxy

When enabled, the person filter proxy restricts the export to people that match a named custom filter. The filter must already exist in your Gramps user data (created via the GUI Filter Editor or the custom filters XML file).

The filter name is set with the export.person-filter configuration key:

gramps -c export.proxy-order:"[['privacy',0],['living',0],['person',1],['note',0],['reference',0]]" \
       -c export.person-filter:"My Paternal Line" \
       -O "Family Tree 1" -e paternal.gramps -f gramps

Note

Note filter proxy

When enabled, the note filter proxy restricts which notes are included in the export, using a named custom note filter. Set the filter name with export.note-filter:

gramps -c export.proxy-order:"[['privacy',0],['living',0],['person',0],['note',1],['reference',0]]" \
       -c export.note-filter:"Public Notes Only" \
       -O "Family Tree 1" -e filtered.gramps -f gramps

Reference filter proxy

When enabled, the reference filter proxy removes any record (source, citation, place, repository, media) that is not linked — directly or indirectly — to at least one person selected by the person filter. This is essential for producing a clean, self-consistent export that contains only the data actually referenced by the selected people.

The reference filter is most useful in combination with the person filter proxy:

gramps -c export.proxy-order:"[['privacy',1],['living',1],['person',1],['note',0],['reference',1]]" \
       -c export.person-filter:"Smith Family" \
       -c export.living-people:3 \
       -O "Family Tree 1" -e smith_public.ged -f ged

This example produces a GEDCOM that: removes private records, excludes living people, limits persons to those matching the "Smith Family" filter, and strips any unreferenced supporting records.

Configuring proxies from the command line

The -c / --config flag sets a configuration value for the current session only (it does not permanently modify your gramps.ini unless no export or action follows — see the Configuration option section). You may chain multiple -c flags before the -O and -e flags.

The key configuration settings for export proxies are:

Setting	Values	Purpose
`export.proxy-order`	JSON array of [name, 0\|1] pairs	Enables/disables each proxy
`export.living-people`	0, 1, 2, or 3	Living proxy restriction mode
`export.person-filter`	Filter name string	Named person filter for person proxy
`export.note-filter`	Filter name string	Named note filter for note proxy

Warning

The -c flags are processed before the export. When used in combination with -O and -e, they affect only the current run and do not permanently write to gramps.ini. If you run gramps -c key:value with no -O, -i, or -e flag, the value is written permanently.

CSV export format

When exporting with -f csv, Gramps writes a plain-text comma-separated file organised into four sections. This format is designed for spreadsheet editing; the exported file can be re-imported with -i filename -f csv to update the database.

Warning

CSV export captures only a subset of your genealogy data. Notes and sources are never exported. Do not use CSV as your sole backup format; use the Gramps XML (.gramps) or package (.gpkg) format for full backups.

The four sections and their column names are:

Places section

Place, Title, Name, Type, Latitude, Longitude, Code, Enclosed_in, Date

People (Person) section

Person, Lastname, Firstname, Callname, Suffix, Prefix, Title, Gender, Birthdate, Birthplace, Birthsource, Baptismdate, Baptismplace, Baptismsource, Deathdate, Deathplace, Deathsource, Burialdate, Burialplace, Burialsource, Note, Grampsid, Marker, Private, Tags

Marriages (Family) section

Family, Father, Mother, Marriagedate, Marriageplace, Marriagesource, Divorcedate, Divorceplace, Divorcesource, Note, Grampsid, Marker, Private, Tags

Children section

Family, Child

Example CLI export to CSV:

gramps -O "Family Tree 1" -e export.csv -f csv

To import a previously exported CSV (to update records):

gramps -O "Family Tree 1" -i updated.csv -f csv

Note

The CSV importer identifies records by Gramps ID (the Grampsid column). Rows without a Grampsid will be treated as new records. See the full CSV Import and Export manual page for detailed import rules and the column format for each section.

Action options

The action to perform on the imported data can be specified with the -a action or --action=action option. This is done after all imports are successfully completed.

The following actions are available:

report: This action allows producing reports from the command line.
tool: This action allows running a tool from the command line.

Reports and tools generally have many options of their own, so these actions should be followed by the report/tool option string. The string is given using the -p option_string or --options=option_string option.

report action option

You can generate most reports from the command line using the report action.

An example:

gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html"

You can provide the css style to use here with the css option:

gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css=Web_Nebraska.css"

or without css in the html output:

gramps -O "Family Tree 1" -a report -p "name=family_group,style=default,off=html,of=test.html,css="

Report option string

The report option string should satisfy the following conditions:

It must not contain any spaces (due to the general nature of the command line interface). If some arguments need to include spaces, the string should be enclosed with quotation marks.
Option string must list pairs of option names and values. Within a pair, option name and value must be separated by the equal sign.
Different pairs must be separated by commas.

Most of the report options are specific for every report. However, there are some common options:

name=report_name: This mandatory option determines which report will be generated.

Report names

If the supplied report_name does not correspond to any available report, an error message will be printed followed by a list of available builtin and addon reports.

Available names include (addon reports will vary by installation):

  ancestor_chart              - Ancestor Tree
  ancestor_report             - Ahnentafel Report
  AncestorFill                - AncestorFill
  birthday_report             - Birthday and Anniversary Report
  calendar                    - Calendar
  d3-ancestralcollapsibletree - Ancestral Collapsible Tree
  d3-ancestralfanchart        - Ancestral Fan Chart
  d3-descendantindentedtree   - Descendant Indented Tree
  database-differences-report - Database Differences Report
  denominoviso                - DenominoViso
  descend_chart               - Descendant Tree
  descend_report              - Descendant Report
  DescendantBook              - Descendant Book
  Descendants Lines           - Descendants Lines
  det_ancestor_report         - Detailed Ancestral Report
  det_descendant_report       - Detailed Descendant Report
  DetailedDescendantBook      - Detailed Descendant Book
  double_cousins              - Double Cousins
  DynamicWeb                  - Dynamic Web Report
  endofline_report            - End of Line Report
  family_descend_chart        - Family Descendant Tree
  family_group                - Family Group Report
  familylines_graph           - Family Lines Graph
  FamilySheet                 - Family Sheet
  FamilyTree                  - Family Tree
  fan_chart                   - Fan Chart
  gt_ancestor                 - Ancestor Tree
  gt_descendant               - Descendant Tree
  gt_grandparent              - Grandparent Tree
  gt_sandclock                - Sandclock Tree
  gt_sandclock_family         - Sandclock Tree for a Family
  Heatmap                     - Heatmap
  hourglass_graph             - Hourglass Graph
  indiv_complete              - Complete Individual Report
  kinship_report              - Kinship Report
  LastChangeReport            - Last Change Report
  LinesOfDescendency          - Lines of Descendency Report
  ListeEclair                 - Tiny Tafel
  MediaReport                 - Media Report
  navwebpage                  - Narrated Web Site
  networkchart                - Network Chart
  notelinkreport              - Note Link Report
  number_of_ancestors         - Number of Ancestors Report
  PedigreeChart               - Pedigree Chart
  PersonEverythingReport      - PersonEverything Report
  place_report                - Place Report
  records                     - Records Report
  rel_graph                   - Relationship Graph
  Repositories Report         - Repositories Report
  SourcesCitationsReport      - Sources and Citations Report
  statistics_chart            - Statistics Charts
  summary                     - Database Summary Report
  tag_report                  - Tag Report
  timeline                    - Timeline Chart
  TimePedigreeHTML            - Timeline Pedigree Report
  TodoReport                  - Todo Report
  WebCal                      - Web Calendar

Common output options:

of=: output filename and optional destination folder/directory e.g.: of="C:\Users\<username>\Desktop\FamilyTree.odt"
off=: output format. These are the extension an output format makes available, e.g., pdf, html, doc, ...
style=: for text reports, the stylesheet to use. Defaults to 'default'.
show=all: This will produce the list of names for all options available for a given report.
show=option_name: This will print the description of the functionality supplied by the option_name, as well as what are the acceptable types and values for this option.

So, to learn to use a report, do for example:

gramps -O "Family Tree 1" -a report -p "name=family_group,show=all"

Note

If an option is not supplied, the last used value will be used. If this report has never been generated before, then the value from the last generated report will be used when applicable. Otherwise, the default value will be used.

When more than one output action is given, each has to be preceded by -a flag. The actions are performed one by one, in the specified order.

Lists

tool action option

You can run most tools from the command line using the 'tool' action. To see which ones, say:

gramps -O "Family Tree 1" -a tool -p show=all

To see a tool's available options, for instance the "verify" tool:

gramps -O "Family Tree 1" -a tool -p name=verify,show=all

To run a tool, for instance the "verify" tool:

gramps -O "Family Tree 1" -a tool -p name=verify

Tool names

If the supplied tool_name does not correspond to any available tool, an error message will be printed followed by this list of available tools:

  Available names are:
    check                              - Check and Repair Database
    chtype                             - Rename Event Types
    dgenstats                          - Dump Gender Statistics
    evname                             - Extract Event Description
    rebuild                            - Rebuild Secondary Indexes
    rebuild_genstats                   - Rebuild Gender Statistics
    rebuild_refmap                     - Rebuild Reference Maps
    reorder_ids                        - Reorder Gramps IDs
    test_for_date_parser_and_displayer - Check Localized Date Displayer and Parser
    testcasegenerator                  - Generate Testcases for Persons and Families
    verify                             - Verify the Data

book action option

You can run books from the command line using the 'book' action.

To see which ones, say:

gramps -O "Family Tree 1" -a book

To see a book's available options, for instance a book called "mybook":

gramps -O "Family Tree 1" -a book -p name=mybook,show=all

To run a book, for instance a book called "mybook":

gramps -O "Family Tree 1" -a book -p name=mybook

Book names

If the supplied book_name does not correspond to any available Book, an error message will be printed followed by this list of available Books (example listing only — books will be whatever you have named them):

  Available names are:
    Granny Jones
    Grampa John
    Smith Family History

Remove option

-r, --remove=FAMILY_TREE_PATTERN

This option permanently removes one or more Family Trees whose names match the given regular expression pattern. This is a destructive, irreversible operation. By default, Gramps will prompt for confirmation before removing each matching tree. Use -y / --yes to suppress the confirmation prompt (non-GUI mode only).

Warning

Removing a Family Tree deletes its database directory. This cannot be undone. Always ensure you have a backup before using -r.

Examples:

# Remove a tree whose name is exactly "Test Tree"
gramps -r "^Test Tree$"

# Remove all trees whose names begin with "Old" without prompting
gramps -r "^Old" -y

The pattern is a Python regular expression matched against the Family Tree name (not the database path).

Force unlock option

-u: you can extend the -O flag with -u to force a locked family to be unlocked. This allows you to recover from a crash that leaves the family tree (database) locked, from the command line.

An example (to unlock the "Family Tree 1" database):

gramps -O "Family Tree 1" -a report -u > /dev/null

Note

It is not possible to open family trees that need repair from the command line.

Configuration (config) option

When all configuration variable(s) are set Gramps will start with these new values.

These options can take three forms (the following examples use behavior.database-path as the configuration variable to change, except for examples 1 and 3.2).

1) See all config values

-s or --show

For example:

gramps --show

Gramps config settings from /home/<~username>/.gramps/gramps60/gramps.ini:
export.proxy-order=[['privacy', 0], ['living', 0], ['person', 0], ['note', 0], ['reference', 0]]
database.compress-backup=True
database.backend='bsddb'
database.backup-path='/home/<~username>'
database.port=''
database.autobackup=0
database.path='/home/<~username>/.gramps/grampsdb'
database.host=''
database.backup-on-exit=True
geography.lock=False
...

2) See a single config value

--config=database.path or -c database.path

For example:

gramps --config=database.path

Current Gramps config setting: database.path:'/home/<~username>/.gramps/grampsdb'

3) Set a value

--config=behavior.database-path:'/media/mydb' or -c behavior.database-path:'/media/mydb'

3.1) Set a value to its default

--config=behavior.database-path:DEFAULT or -c behavior.database-path:DEFAULT

3.2) Set more than one value

--config=behavior.use-tips:False --config=behavior.autoload:True or -c behavior.use-tips:False -c behavior.autoload:True

Note

When -c is used together with -O, -i, or -e in the same command, the configuration value is applied for the current session only and is not written permanently to gramps.ini. When -c is used alone (with no open/import/export), the value is written permanently.

Safe mode

gramps -S

or

gramps --safe

This CLI command starts Gramps as if it had never been installed before. In this mode, any previous family trees can still be loaded, as long as they were stored in the default folder. All other settings, filters, books, addons etc. are either cleared or returned to their default values. Other CLI commands can be used, or, if none, Gramps will start the GUI. Nothing except the actual family tree data is saved.

Note that this is typically used to see if Gramps behaves better when it is running as if with a totally 'clean' install. It is NOT permanent (if you want that see Defaults below). If you start Gramps normally after using this command all of your previous settings etc. are still there.

This actually works by setting the folder that Gramps uses to store its user data (except for family trees) to a temporary directory, which is deleted when Gramps closes.

Defaults

gramps -D E

or

gramps --default=E

This CLI command causes Gramps to clear out or return to defaults the desired settings. The family tree databases are NOT cleared out or removed. The sub-commands (replace the 'E' from the example command line above with one or more of the subcommand characters) are:

A Addons are cleared. Any installed addons are removed, along with their settings.
F Filters are cleared. Any custom filters are removed.
P Preferences are returned to their default values.
X Books are cleared, Reports and Tools settings are returned to their default values.
Z Old .zip files from family tree version upgrades are deleted.
E Everything except the actual family tree data is returned to default settings. This does all of the above as well as a few more items; deletes thumbnails, maps, and the user CSS (used in web reports).

For example:

gramps -D AP

will cause Gramps to remove all the Addons and to reset Preferences to their default values.

Database credentials

-U, --username=USERNAME
-P, --password=PASSWORD

These options supply a username and password when opening a Family Tree that uses a network database backend requiring authentication (for example, the PostgreSQL backend). They are not used with the default SQLite backend.

Security warning

Supplying a password on the command line may expose it in shell history, process listings (ps aux), and log files. Where possible, prefer configuring database credentials through the backend's own secure mechanism (e.g. a .pgpass file for PostgreSQL) rather than using -P.

Example:

gramps -O "Family Tree 1" -U myuser -P mysecretpass -e backup.gramps -f gramps

Creating a new Family Tree

-C, --create=FAMILY_TREE

When combined with -O, the -C flag creates a new Family Tree with the given name if one does not already exist, then opens it. If a tree with that name already exists, it is simply opened. This is useful in scripted pipelines where you want to create-or-open a tree in a single step before importing data.

Example — create (or open) a tree named "Import Test" and import a GEDCOM into it:

gramps -O "Import Test" -C "Import Test" -i data.ged -f ged

Loading dynamic modules

--load-modules=MODULE1,MODULE2,...

This option loads one or more Python modules dynamically at startup, before any other processing. Modules are specified as a comma-separated list of fully-qualified module names or file paths. This is an advanced option intended for plugin developers and automated testing scenarios where custom code needs to be injected into the Gramps plugin registry before CLI actions are performed.

Example:

gramps --load-modules=mypackage.myplugin -O "Family Tree 1" -a report -p name=myreport,off=pdf,of=out.pdf

Operation

If the first argument on the command line does not start with a dash (i.e. no flag), Gramps will attempt to open the file with the name given by the first argument and start an interactive session, ignoring the rest of the command line arguments.

If the -O flag is given, then Gramps will try opening the supplied file name and then work with that data, as instructed by the further command line parameters.

Only one file can be opened in a single invocation of Gramps.

If you need to get data from multiple sources, use the importing options by using -i flag.

With or without the -O flag, there could be multiple imports, exports, and actions specified further on the command line by using -i, -e, and -a flags.

The order of -i, -e, or -a options with respect to each other does not matter. The actual execution order always is: all imports (if any) → all exports (if any) → all actions (if any).

Note

Opening must always be first!

If no -O or -i option is given, Gramps will launch its main window and start the usual interactive session with the empty database, since there is no data to process, anyway. (Unless you have already expressed a "preference" that it start with the last database it used.)

If no -e or -a options are given, Gramps will launch its main window and start the usual interactive session with the database resulted from opening and all imports (if any). This database resides in a directory under the ~/.gramps/grampsdb/ directory.

Any errors encountered during import, export, or action, will be either dumped to stdout (if these are exceptions handled by Gramps) or to stderr (if these are not handled). Use usual shell redirections of stdout and stderr to save messages and errors in files.

Examples

To import four databases (whose formats can be determined from their names) and then check the resulting database for errors, one may type:

gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps -i file4.wft -a check

To explicitly specify the formats in the above example, append filenames with appropriate -f options:

gramps -i file1.ged -f gedcom -i file2.gpkg -f gramps-pkg -i ~/db3.gramps -f gramps-xml -i file4.wft -f wft -a check

To record the database resulting from all imports, supply -e flag (use -f if the filename does not allow Gramps to guess the format):

gramps -i file1.ged -i file2.gpkg -e ~/new-package -f gramps-pkg

To save any error messages of the above example into files outfile and errfile, run:

gramps -i file1.ged -i file2.dpkg -e ~/new-package -f gramps-pkg >outfile 2>errfile

To import three databases and start interactive Gramps session with the result:

gramps -i file1.ged -i file2.gpkg -i ~/db3.gramps

To open a database and, based on that data, generate timeline report in PDF format putting the output into the my_timeline.pdf file:

gramps -O 'Family Tree 1' -a report -p name=timeline,off=pdf,of=my_timeline.pdf

Listing report options

To convert the bsddb database on the fly to a .gramps xml file:

gramps -O 'Family Tree 1' -e output.gramps -f gramps-xml

To generate a web site into another locale (in German):

LANGUAGE=de_DE; LANG=de_DE.UTF-8 gramps -O 'Family Tree 1' -a report -p name=navwebpage,target=/../de

To export simultaneously to both Gramps XML (backup) and GEDCOM (for sharing with another program):

gramps -O 'Family Tree 1' -e backup.gramps -f gramps -e share.ged -f ged

To export a GEDCOM excluding all private records, omitting living people entirely, and limiting the export to people matched by an existing filter named "Public Ancestors":

gramps \
  -c export.proxy-order:"[['privacy',1],['living',1],['person',1],['note',0],['reference',1]]" \
  -c export.living-people:3 \
  -c export.person-filter:"Public Ancestors" \
  -O 'Family Tree 1' -e public_ancestors.ged -f ged

To export to CSV for spreadsheet editing:

gramps -O 'Family Tree 1' -e mydata.csv -f csv

Finally, to start normal interactive session type:

gramps

Environment variables

Warning

Gramps can take advantage of the following environment variables. Only change them if you know what you are doing.

GRAMPSHOME

GRAMPSHOME - if set, overrides the default path to the profile, allowing a user to use an external network drive to store data and all settings. For technically advanced users who run multiple versions of Gramps, setting a different $GRAMPSHOME is a way to avoid interference between the different versions in the Gramps User Directory. It can also be used to configure Gramps to run from a portable drive or to prepare for a manual installation. The path can also be used to configure the path to a separate test Tree or development Tree.

For example:

GRAMPSHOME=$HOME/familytrees/paternal

LANG, LANGUAGE, LC_MESSAGES, LC_TIME

LANG, LANGUAGE, LC_MESSAGES, and LC_TIME - are used by Gramps to determine which language file(s) should be loaded. See locale for a general discussion of LANG, LC_MESSAGES, and LC_TIME. Note that in addition to setting date formats (which are overridden in Gramps with Preferences settings) LC_TIME also sets the language used for words in dates like month and day names and in the context of dates words like about, between, and before. LANGUAGE is a comma-separated list of language codes (not locales, though certain languages like pt_BR or cn_TW are regional variants) that sets a preference-ordered list of desired translations. It will override LANG but not LC_MESSAGES or LC_TIME.

macOS

Because of the way launching with Finder works, the environment variables for the Gramps.app bundle are hard-coded in Gramps.app/Contents/Resources/gramps_launcher.py. If for some reason you need to change them, edit the file with TextEdit; be sure to save it back as plain text. See as well setting locale for an alternative to using the LANG and LANGUAGE environment variables.

GRAMPSI18N

$GRAMPSI18N (for your locale) - The LANG assumes the Gramps translations are installed globally. If this is not the case, you need to give Gramps the directory where the translations will be found. This can be used to temporarily change the language for Reports being generated.

A translation is called gramps.mo; you can find it in Linux with the locate command. For example, if you have Swedish in directory /home/me/gramps/mo/sv/gramps.mo, you can direct Gramps there using:

GRAMPSI18N=/home/me/gramps/mo LC_ALL=C.UTF-8 LANG="sv" python3 gramps

GRAMPSDIR

The environment variable GRAMPSDIR is the path to your Gramps directory.

GRAMPS_RESOURCES

The environment variable GRAMPS_RESOURCES is the path to Gramps built-in resources files. You should only change this if you are using Gramps from source code or a custom environment. An indicator that you need to set this variable is if you receive one of the following errors:
- Encoding error while parsing resource path
- Failed to open resource file
- Resource Path {invalid/path/to/resources} is invalid
- Unable to determine resource path

Example usage:

GRAMPS_RESOURCES=/home/username/gramps/branches/maintenance/gramps60/build/t \
  PYTHONPATH=$GRAMPS_RESOURCES:$PYTHONPATH ./gramps

Special copyright notice

All edits to this page need to be under two different copyright licenses:

GNU Free Documentation License 1.2 - see wiki copyright
GPL - see manual copyright

These licenses allow the Gramps project to maximally use this wiki manual as free content in future Gramps versions. If you do not agree with this dual license, then do not edit this page. You may only link to other pages within the wiki which fall only under the GFDL license via external links (using the syntax: [https://www.gramps-project.org/...]), not via internal links.

Also, only use the known Typographical conventions

Talk:Gramps 6.0 Wiki Manual - Command Line

Contents

Gramps 6.0 Wiki Manual - Command Line

Contents

Start Gramps through the Command Line

Linux

MS Windows

macOS

Python options

Available Gramps options

Help options

Usage message

List options

Sparse

Detailed

Tab delimited

Version options

Format options

Full family tree support

Reduced family tree support

Subset of your data

Opening options

Import options

Export options

Exporting more files

Export filters and privacy proxies

Privacy proxy

Living-person proxy

Person filter proxy

Note filter proxy

Reference filter proxy

Configuring proxies from the command line

CSV export format

Action options

report action option

Report option string

Report names

tool action option

Tool names

book action option

Book names

Remove option

Force unlock option

Configuration (config) option

1) See all config values

2) See a single config value

3) Set a value

3.1) Set a value to its default

3.2) Set more than one value

Safe mode

Defaults

Database credentials

Creating a new Family Tree

Loading dynamic modules

Operation

Examples

Environment variables

GRAMPSHOME

LANG, LANGUAGE, LC_MESSAGES, LC_TIME

macOS

GRAMPSI18N

GRAMPSDIR

GRAMPS_RESOURCES

Navigation menu

Search