Written and maintained by CASRAI Editorial Board
Published
On this page
gtsummary is an R package that turns a data frame or a fitted model into a formatted table: a “Table 1” of participant characteristics, a regression results table, or a merged side-by-side table. This guide is for researchers and analysts who work in R and need to go from a data frame to a table they can drop into a manuscript. It covers what the package does, how to install it, a worked Table 1 and regression table, how to read the default output, and the documented causes of the most common surprises.
Facts about the package below were read from the package website and CRAN on 2026-11-07. At that date the current release on CRAN was gtsummary 2.6.1, published 2026-09-04, under an MIT licence.
What gtsummary is used for in research
The package documentation describes it as providing “an elegant and flexible way to create publication-ready analytical and summary tables.” CRAN describes it as creating “presentation-ready tables summarizing data sets, regression models, and more.” In research practice that covers three jobs:
- Descriptive tables (usually Table 1) with
tbl_summary(), optionally split by a grouping variable such as treatment arm. - Group comparisons by adding p-values to that table with
add_p(). - Model tables with
tbl_regression(), for example odds ratios with 95% confidence intervals from a logistic model.
The package was described in the R Journal (2021, volume 13, pages 570-580, doi:10.32614/RJ-2021-053); cite that paper if gtsummary produced a table in your work. CRAN lists Daniel D. Sjoberg as maintainer.
Install or access
Install the released version from CRAN:
install.packages("gtsummary")
library(gtsummary)
The package website gives this route for the development version from GitHub:
pak::pkg_install("ddsjoberg/gtsummary", dependencies = TRUE)
CRAN lists, among its imports, the cards, cardx, cli, dplyr and gt packages (gt version 0.11.1 or later), which install automatically. gtsummary is R-only; the documentation and CRAN page describe an R package and no Python port is documented there.
Step-by-step: from a data frame to Table 1 and a regression table
The package website demonstrates the workflow with its built-in trial data set. Substitute your own data frame; the cleaning rules described under “Output and how to read it” apply to it.
- Load the package and your data.
library(gtsummary). Know your variable types first; see data frames in R for the structure gtsummary expects. - Build the overall summary.
table1 <- trial |> tbl_summary(include = c(age, grade, response)). Theincludeargument chooses which columns appear. - Stratify by group. Add
by = trtto split the columns by treatment arm, for exampletbl_summary(by = trt, include = c(age, grade, response)). - Add p-values and an overall column. Pipe the result to
add_p()and, if wanted,add_overall(). - Relabel variables. Pass
label = list(age = "Age, years")totbl_summary(). - Build a regression table. Fit a model, then pass it to
tbl_regression(). For a logistic model, setexponentiate = TRUEso the estimate column shows odds ratios; the reference page’s own example footer reads “OR = Odds Ratio, CI = Confidence Interval”. - Combine tables.
tbl_merge()places several gtsummary tables side by side. - Export.
as_gt()converts a table to a gt object, which can be saved withgt::gtsave().as_flex_table()converts it to a flextable object; the reference page notes that the gt package does not support Word, which is why a flextable route exists for Word output.
Output and how to read it
The default statistics come from the tbl_summary() reference page (read 2026-11-07):
| Variable type | Default statistic | What the cell shows |
|---|---|---|
| Continuous | {median} ({p25}, {p75}) |
Median with the 25th and 75th percentiles (the interquartile range bounds) |
| Categorical | {n} ({p}%) |
Count with percentage |
- Percent basis. The
percentargument defaults to"column";"row"and"cell"are the alternatives. - Missing data.
missingdefaults to"ifany", which adds a missing row only for variables that have missing values. The row is labelled “Unknown” by default (missing_text) and shows the count of missing observations (missing_stat = "{N_miss}")."no"and"always"are the other options. - Which p-value test
add_p()used. With abyvariable and nogrouporadj.vars, the documented defaults are the Wilcoxon rank-sum test for continuous variables with two groups, the Kruskal-Wallis test for three or more groups, and a chi-squared test without continuity correction for categorical variables when all expected counts are at least 5, switching to Fisher’s exact test when any expected count is below 5. Override withtest = everything() ~ "t.test", for example. The default p-value format rounds to one digit (label_style_pvalue(digits = 1)); passpvalue_fun = label_style_pvalue(digits = 2)for two.
Because the defaults are non-parametric and report medians, state in your methods text which statistic and test each row used. For guidance on interpreting the model table, see how to read a regression table; for the descriptive statistics themselves, see summary statistics in R. Reporting conventions for statistics in journals are covered in APA statistics reporting.
Troubleshooting
| Symptom | Documented cause and fix |
|---|---|
| A numeric variable (for example a 1-5 score) is summarised as counts and percentages instead of a median | Per the reference page, numeric variables with fewer than 10 unique levels default to categorical. Set type = list(score ~ "continuous") to force it. Valid types are "continuous", "continuous2", "categorical" and "dichotomous". |
| A yes/no variable shows one row instead of one row per level | Variables coded TRUE/FALSE, 0/1 or yes/no are assumed dichotomous and display a single row. Use type = list(var ~ "categorical") to show every level. |
| You want a mean (SD) instead of a median (IQR) | Set statistic = all_continuous() ~ "{mean} ({sd})". |
| No p-value for a grouped (clustered) comparison with three or more groups | The add_p.tbl_summary reference states there is no default for grouped data when the by variable has more than two levels; choose a test explicitly with test. |
| Regression estimates look like log-odds | exponentiate defaults to FALSE; set exponentiate = TRUE for odds ratios from a logistic model. |
Free alternatives
Other CRAN packages build Table 1-style summaries. Descriptions below are quoted or paraphrased from each package’s CRAN page (read 2026-11-07).
| Package | What CRAN says it does | Version and date on CRAN | Licence |
|---|---|---|---|
| gtsummary | Presentation-ready tables summarising data sets and regression models | 2.6.1, 2026-09-04 | MIT |
| tableone | Creates “Table 1”, a description of baseline patient characteristics; supports continuous and categorical variables, p-values and standardized mean differences; weighted data via the survey package | 0.13.2, 2022-04-15 | GPL-2 |
| arsenal | tableby() for Table 1-style summaries by group, paired(), modelsum(), freqlist(), comparedf() and write2() for document output |
3.7.4, 2026-10-17 | GPL-2 | GPL-3 |
Pick by the output you need: only gtsummary’s documentation covers regression tables with tbl_regression() and conversion to gt and flextable objects, while tableone’s CRAN description highlights standardized mean differences and survey-weighted data.
FAQ
What is gtsummary in R?
An R package for creating publication-ready summary and regression tables from data frames and fitted models. As of 2026-11-07 the current CRAN version is 2.6.1.
How do I install gtsummary?
Run install.packages("gtsummary") in R, then library(gtsummary).
Is there a Python version of gtsummary?
The package documentation and CRAN page describe an R package only. This guide does not cover a Python equivalent.
How do I make a Table 1 grouped by treatment?
Use tbl_summary(by = trt) and pipe to add_p() to add between-group p-values.
Can gtsummary export to Word?
Convert the table with as_flex_table(), which returns a flextable object; the gtsummary reference notes the gt package does not support Word.
Sources
- gtsummary package website, danieldsjoberg.com/gtsummary, including the reference pages for
tbl_summary,add_p.tbl_summary,tbl_regressionandas_flex_table(read 2026-11-07). - CRAN: gtsummary, tableone, arsenal (read 2026-11-07).
- The R Journal, 2021, volume 13, pages 570-580, doi:10.32614/RJ-2021-053 (the gtsummary package paper).







