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.
- Build the genetic relationship matrix (GRM).
gcta64 --bfile test --autosome --maf 0.01 --make-grm --out test --thread-num 10This writes
test.grm.bin(the lower triangle of the GRM, binary),test.grm.N.bin(the number of SNPs used for each pair) andtest.grm.id(a text file with no header; columns are family ID and individual ID).--maf 0.01excludes SNPs with minor allele frequency below 0.01. For non-human species add--autosome-num Nto give the number of autosomes. - 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 10for each chromosome, list the file prefixes (one per line) ingrm_chrs.txt, then merge:gcta64 --mgrm grm_chrs.txt --make-grm --out test - Optional: remove close relatives.
gcta64 --grm test --grm-cutoff 0.025 --make-grm --out test_rm025The tutorial itself warns that the 0.025 cutoff is “quite arbitrary”; state the cutoff you use and why.
- Run GREML (REML analysis).
gcta64 --grm test --pheno test.phen --reml --out test --thread-num 10Results go to
test.hsq. To adjust for principal components, add a covariate file:--qcovar test_10PCs.txt. - 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
-9orNA. 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 10The 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
- GCTA official website, overview, download, update log, GREML tutorial and FAQ: yanglab.westlake.edu.cn/software/gcta (read 2026-11-08).
- GCTA source and README: github.com/JianYang-Lab/GCTA (read 2026-11-08).
- Yang J, Lee SH, Goddard ME, Visscher PM. GCTA: a tool for genome-wide complex trait analysis. Am J Hum Genet 2011;88(1):76-82. PubMed 21167468.
- Yang J et al. Common SNPs explain a large proportion of the heritability for human height. Nat Genet 2010;42(7):565-569. PubMed 20562875.
- PLINK: cog-genomics.org/plink/2.0; regenie: rgcgithub.github.io/regenie; BOLT-LMM manual: alkesgroup.broadinstitute.org/BOLT-LMM; LDAK: dougspeed.com/ldak (all read 2026-11-08).







