Skip to main content
v2026.11,986 entries · CC-BY 4.0

GCTA (Genome-wide Complex Trait Analysis): GREML Heritability Step by Step

How to run GCTA (Genome-wide Complex Trait Analysis): install, build a GRM, estimate SNP heritability with GREML, read .hsq output, and troubleshoot.

Written and maintained by CASRAI Editorial Board

Published · Last updated

On this page

GCTA (Genome-wide Complex Trait Analysis) is a free command-line program that estimates how much of the variation in a trait is explained by all the genotyped SNPs together (SNP-based heritability, via GREML) and also runs mixed-model association, conditional analysis and Mendelian randomisation. This guide walks the core GREML workflow end to end (genetic relationship matrix, REML, reading the .hsq file) and lists the traps in the official manual that most often stall a first run. Commands and details were checked against the official GCTA website on 2026-11-08.

What GCTA is used for in research

The GCTA site describes the package as software “initially developed to estimate the proportion of phenotypic variance explained by all genome-wide SNPs for a complex trait” and since extended to many other analyses of data from genome-wide association studies. Its original developers are Jian Yang, Peter Visscher, Mike Goddard and Hong Lee; Jian Yang maintains it. The two papers the site asks users to cite for the core method are Yang et al. 2011, Am J Hum Genet 88(1):76-82 (PubMed 21167468) and Yang et al. 2010, Nat Genet 42(7):565-569 (PubMed 20562875).

If you are new to association testing itself, start with the CASRAI guide to the genome-wide association study; for how significance is judged afterwards, see genome-wide significance thresholds.

Which GCTA module for which question

The modules named in the site overview, grouped by the question they answer:

Question Module (from the GCTA overview)
How related are my samples, and how inbred? Genetic relationship matrix (GRM); inbreeding coefficients
How much trait variance do all SNPs explain? GREML (SNP-based heritability); partitioning variance by chromosome, MAF or annotation; GREMLd (dominance); bivariate GREML (genetic correlation); Haseman-Elston regression
Association testing that allows for relatedness? MLMA and MLMA-LOCO (dense GRM); fastGWA and fastGWA-GLMM (sparse GRM)
Which signals are independent, or what do summary statistics imply? COJO and mtCOJO (conditional analysis); fastBAT, mBAT-combo and ACAT-V (gene- and set-based tests); GSMR (Mendelian randomisation); LD scores
Prediction and simulation? sBLUP; phenotype simulation; PCA and Fst

How to install or access it

Download the compiled executable from the official site, yanglab.westlake.edu.cn/software/gcta. As read on 2026-11-08 the download section lists a Linux x86_64 build (1.95.4), a Windows x86_64 build (1.95.1) and a macOS arm64 build (1.95.4), plus a macOS x86_64 build (1.94.1). The site says the executables are released under the MIT licence and recommends the Linux version because the Windows and Mac versions have not been fully tested; its update log shows version 1.95.4 dated 14 October 2026. Check the update log for the current release before you cite a version in a methods section.

  • The Linux build needs kernel 2.6.32 or later; older kernels give the error FATAL: kernel too old.
  • Source code is at github.com/JianYang-Lab/GCTA under GPL v3. Building from source on Linux needs, per the README, an x86_64 CPU (or AArch64 with OpenBLAS), Intel MKL 2017 or later, Eigen 3.3.7, CMake 3.1 or later, Boost, zlib, sqlite3, zstd, Spectra and GSL, and GCC 6.1 or later. The README gives no compile instructions for Mac or Windows; use the binaries.
  • The manual invokes the program as gcta64. Run it from the folder holding the executable or put it on your PATH.

Step-by-step: estimate SNP-based heritability with GREML

The following sequence is the official GREML tutorial. It assumes PLINK binary genotype files test.bed, test.bim and test.fam and a phenotype file test.phen. Replace names with your own; --thread-num sets the number of CPU threads.

  1. Build the genetic relationship matrix (GRM).
    gcta64 --bfile test --autosome --maf 0.01 --make-grm --out test --thread-num 10

    This writes test.grm.bin (the lower triangle of the GRM, binary), test.grm.N.bin (the number of SNPs used for each pair) and test.grm.id (a text file with no header; columns are family ID and individual ID). --maf 0.01 excludes SNPs with minor allele frequency below 0.01. For non-human species add --autosome-num N to give the number of autosomes.

  2. Optional: build the GRM per chromosome and merge. For large data, run gcta64 --bfile test --chr 1 --maf 0.01 --make-grm --out test_chr1 --thread-num 10 for each chromosome, list the file prefixes (one per line) in grm_chrs.txt, then merge:
    gcta64 --mgrm grm_chrs.txt --make-grm --out test
  3. Optional: remove close relatives.
    gcta64 --grm test --grm-cutoff 0.025 --make-grm --out test_rm025

    The tutorial itself warns that the 0.025 cutoff is “quite arbitrary”; state the cutoff you use and why.

  4. Run GREML (REML analysis).
    gcta64 --grm test --pheno test.phen --reml --out test --thread-num 10

    Results go to test.hsq. To adjust for principal components, add a covariate file: --qcovar test_10PCs.txt.

  5. Case-control traits. Code case-control status in the phenotype file as 0 and 1, or 1 and 2 as in PLINK; missing values are -9 or NA. Supply the population disease prevalence so GCTA also reports the liability-scale estimate:
    gcta64 --grm test --pheno test_cc.phen --reml --prevalence 0.01 --out test --thread-num 10

    The value 0.01 is the tutorial’s example; use the prevalence appropriate to your trait and population.

Other data-management flags that appear in the manual: --keep and --remove (select or drop individuals from a file), --chr, --max-maf and --update-sex.

Output and how to read it

The .hsq file has three columns: Source, Variance and SE. The rows, as in the manual:

Row Meaning
V(G) (or V(1), V(2) when you pass several GRMs) Variance explained by the SNPs captured in the GRM
V(e) Residual variance
Vp Total phenotypic variance (sum of the above)
V(G)/Vp The SNP-based heritability estimate, with its standard error
logL, logL0, LRT, Pval Log-likelihood of the full model, log-likelihood without the genetic component, the likelihood-ratio test statistic and its p-value
n Number of individuals analysed

For a case-control run the file adds V(G)/Vp_L, the estimate transformed to the liability scale using your prevalence. Report the liability-scale value for disease traits; the plain V(G)/Vp is on the observed 0-1 scale. The manual’s example output shows V(1)/Vp of 0.400573 (SE 0.164937) for a quantitative trait and, for its case-control example, V(1)/Vp_L of 0.657621 with Pval 4.41e-4 and n 2000. These are demonstration numbers from the tutorial, not results from real data, so do not quote them as findings.

To save predicted genetic values (BLUPs), add --reml-pred-rand; they are written to test.indi.blp, a file with no header whose columns are family ID, individual ID, then the genetic-value and residual columns.

Troubleshooting

V(G)/Vp is exactly 0.9999

By default GCTA does not allow a variance component to be negative. When the estimate wants V(e) to go negative, V(e) is held at 10-6 and V(G)/Vp is pinned at 0.9999. The official FAQ says you can add --reml-no-constrain to allow V(G)/Vp above 1 on the observed scale in case-control data, but warns that artefacts between cases and controls (for example when they were genotyped on different plates or in different labs) will then be estimated as “genetic” variance. Fix batch differences before you rely on the result.

Negative or unstable heritability estimates

The FAQ explains that, to get an unbiased estimate of h2, the estimate should be allowed to go negative (--reml-no-constrain), and that small sample size is one scenario in which estimates fluctuate widely because the sampling variance is large.

fastGWA appears to ignore relatedness

Without --grm-sparse, the --fastGWA-* options run plain linear regression, with no correction for relatedness. Build a sparse GRM from a dense one with --make-bK-sparse 0.05 and pass it with --grm-sparse test_sp_grm, then use --fastGWA-mlm (or --fastGWA-mlm-exact, or --fastGWA-lr). The default variance estimator is REML; --est-vg HE selects Haseman-Elston.

FATAL: kernel too old, or a Mac run fails

The kernel error is the Linux 2.6.32 requirement above. For the macOS arm64 build, the site notes that environment variables must be set as described in the configuration manual shipped inside the download.

Free alternatives

GCTA itself is free to download and its source is GPL v3. The tools below were checked on their own official pages on 2026-11-08; the table records only what those pages say, not a ranking.

Tool What its official page says it does Licence or cost wording on that page
PLINK 1.9 / 2.0 Whole-genome association analysis toolset for basic, large-scale analyses; PLINK 2.0 handles VCF files and dosage data “free, open-source”
regenie Whole-genome regression for large GWAS; quantitative and binary traits; handles population structure and relatedness; Firth and SPA tests for binary traits MIT licence
BOLT-LMM (BOLT-REML) Mixed-model association testing; BOLT-REML estimates heritability explained by genotyped SNPs and genetic correlations, and the manual compares its approach to GCTA See the manual (v2.5)
LDAK Estimates SNP heritability from individual-level data or summary statistics; also association testing and polygenic-score tools See the LDAK site

For the wider picture of general statistics packages, the CASRAI comparison SPSS vs R covers desktop statistical software; GCTA is a specialist genetics tool and does not replace those.

FAQ

What does GCTA stand for?

Genome-wide Complex Trait Analysis. It is the name of both the software package and the 2011 paper (Yang et al., Am J Hum Genet 88(1):76-82) that introduced it.

What is GREML?

GREML is the REML-based method in GCTA that estimates the variance a trait gets from all genome-wide SNPs, using a GRM built from the genotypes. The ratio V(G)/Vp is the SNP-based heritability.

Is GCTA free?

The official site states that the source code is released under GPL v3 and the executables under the MIT licence.

Does GCTA run on Windows or Mac?

Yes: the site provides Windows and macOS builds, but recommends Linux because the other versions are less fully tested.

What input files does GCTA need?

The tutorial uses PLINK binary files (.bed, .bim, .fam) and a phenotype file; the GRM is then stored as .grm.bin, .grm.N.bin and .grm.id.

Sources

Follow CASRAI

Research-administration guidance, standards updates and independent tool reviews.

Ask CASRAI · free to try

Ask about GCTA (Genome-wide Complex Trait Analysis): GREML Heritability Step by Step

2 free questions a day, no account.

An AI assistant for research: funder rules, compliance, methods and publishing. It links the sources behind its answers and labels answers that come from a web search.

Answers draw on CASRAI's guides and dictionary plus the federal and funder documents we index: Federal Register, Grants.gov, Regulations.gov and UKRI.

Works on this site and inside Claude, Cursor and the AI tools you already use.

Everything CASRAI publishes — this page, the dictionary, the guides and the news — stays open to read, with no account and no card.

Referenced across the research world

University of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logoUniversity of Cambridge logoColumbia University logoCrossref logoUniversity of Edinburgh logoHarvard University logoUniversity of Oxford logoPrinceton University logoStanford School of Medicine logoUniversity College London logoORCID logo
  • University of Cambridge logo
  • Columbia University logo
  • Crossref logo
  • University of Edinburgh logo
  • Harvard University logo
  • University of Oxford logo
  • Princeton University logo
  • Stanford School of Medicine logo
  • University College London logo
  • ORCID logo

View CASRAI adoption →