liftOver: Convert hg19 to hg38 Coordinates

liftOver converts genomic coordinates from one genome assembly to another, for example from hg19 (GRCh37) to hg38 (GRCh38), using a chain file that records how the two assemblies align. UCSC offers it as a web tool and as a Linux command-line program; CrossMap is an open-source alternative that also handles VCF, BAM and GTF files. This page is for researchers who hold a BED, VCF or similar file in an old assembly and need it in a new one, and covers the settings, the commands, and how to check what did not convert. Documentation read 2026-11-07.

What liftOver is used for in research

Annotation tracks, peak calls, variant lists and published coordinates are tied to the assembly they were made on. When a collaborator, database or pipeline uses a different assembly, positions no longer line up. liftOver remaps intervals using a UCSC chain file (an over.chain file) for the chosen pair of assemblies, so you do not have to re-run the original analysis. The UCSC Genome Browser documentation describes the web tool under “Converting data between assemblies”. For background on why hg19 and hg38 differ, see hg19 vs hg38 and GRCh38 vs hg38 vs b37.

UCSC states that liftOver is not recommended for SNPs identified by rsID.

Install or access (official source only)

Web tool: the UCSC Genome Browser “Lift Genome Annotations” page (genome.ucsc.edu/cgi-bin/hgLiftOver). No installation. UCSC recommends the command-line tool for files over 500 Mb.
Command line: the liftOver executable is a Linux program distributed by UCSC, linked from the downloads FAQ. You also need the over.chain file for your assembly pair, linked from each assembly’s “LiftOver files” entry on the Downloads page. UCSC states that commercial users must purchase a license for the command-line version; check the UCSC license terms before use.
CrossMap: a Python package released under GPL v2 or later, installed with pip install CrossMap and upgraded with pip install --upgrade CrossMap.

liftOver hg19 to hg38: step by step

Option 1: UCSC web tool (UCSC liftOver tool)

Open the Lift Genome Annotations page. Set the original genome and assembly (for example Human, hg19/GRCh37) and the new assembly (for example hg38/GRCh38). The assembly list also includes T2T CHM13v2.0 (hs1).
Paste your regions into the box or upload a file. BED input uses 0-based starts; the “position box” format (chr:start-end) is 1-based. Mixing the two is the commonest cause of off-by-one results; see BED file format and 0-based coordinates.
Adjust the parameters in the table below if needed. The defaults suit most same-species conversions.
Submit, then download the converted file and the file of regions that could not be converted.

Option 2: UCSC command line

Download the liftOver binary (Linux) and make it executable.
Download the chain file for your pair, for hg19 to hg38: https://hgdownload.gi.ucsc.edu/goldenPath/hg19/liftOver/hg19ToHg38.over.chain.gz (confirmed reachable 2026-11-07), and decompress it.
Run the command, whose usage in the UCSC downloads FAQ is: liftOver oldFile map.chain newFile unMapped. For example: liftOver peaks.hg19.bed hg19ToHg38.over.chain peaks.hg38.bed peaks.unmapped.bed. Regions that could not be converted are written to the unMapped file.

Option 3: CrossMap

Install with pip install CrossMap and obtain a chain file for your pair (for example GRCh37_to_GRCh38.chain.gz, as in the CrossMap documentation).
For BED: CrossMap bed input.chain input.bed [out_bed]. If you omit the output name the result prints to the console. Unmapped records go to out.unmap.
For VCF: CrossMap vcf [--chromid {a,s,l}] [--no-comp-alleles] [--compress] input.chain input.vcf refgenome.fa out_vcf. The refgenome.fa argument is the FASTA of the target assembly. Unmapped records are written to out_vcf.unmap.

CrossMap accepts BAM, CRAM, SAM, BED, Wiggle, BigWig, GFF, GTF, VCF, GVCF and MAF input. If you convert alignments and need to search them afterwards, rebuild the index; see BAM index (.bai) files.

UCSC web tool parameters and defaults

Parameter	Documented default	What it does
Minimum ratio of bases that must remap	0.95	Fraction of a region that must map for it to be converted. UCSC notes values as low as 0.01 for poor-quality or cross-species conversions.
Allow multiple output regions	Off	Lets a region that splits across the new assembly return more than one output region.
Minimum hit size in query	0	Option to drop small query-side hits; UCSC notes it can remove small targets from repeats or transposons.
Minimum chain size in target	0	Discards matches to short chains in the new assembly. UCSC cites a setting of 4,000 as working well for large-scale conversions.
Keep original positions in output	Option in the form	Retains the original coordinates alongside the new ones.
BED 12: minimum ratio of alignment blocks or exons that must map	1	For transcripts, the share of exons that must map.
BED 12: if exon is not mapped, use the closest mapped base	Off	Lets partially mapped transcripts convert.

Source: UCSC Genome Browser help, “Converting data between assemblies”, read 2026-11-07. The web tool takes BED 4-6 for regions and BED 12 for transcripts.

Output and how to read it

You get two files: the converted coordinates in the new assembly and a file of regions that could not be converted. Do not assume a region is wrong because it is absent from the output; it may simply fall in sequence that has no counterpart in the new assembly. A practical quality check: compare the number of input lines with converted plus unmapped lines, and inspect a few unmapped records in a genome browser. If you enabled multiple output regions, the output can have more lines than the input. The contents of the unmapped file are not described in UCSC’s downloads FAQ, so inspect your own file rather than relying on a fixed format.

Which tool to use

Situation	Web tool	UCSC command line	CrossMap
File size	UCSC advises the command line above 500 Mb	Recommended above 500 Mb	No limit documented
Operating system	Any browser	Linux executable	Python package
Formats	BED, position box	Old file, chain file, new file, unMapped file	BAM, CRAM, SAM, BED, Wiggle, BigWig, GFF, GTF, VCF, GVCF, MAF
VCF	Not listed on the tool page	Not described in the FAQ	Supported; needs target-assembly FASTA
Licence	Web form; see UCSC terms	Commercial users must buy a licence	GPL v2 or later

Troubleshooting

Many regions are unmapped

Lower the minimum ratio of bases that must remap only if the loss is acceptable for your analysis; the default 0.95 is deliberately strict. Regions in sequence that was added, removed or rearranged between assemblies may legitimately fail.

Coordinates are shifted by one

Check whether the input was BED (0-based) or position-box format (1-based). UCSC tables almost always use 0-based starts.

The conversion pair is not offered

UCSC notes that a sequential conversion through an intermediate assembly (for example mm9 to mm10 to mm39) may work when no direct pair exists. Every extra step can lose more regions.

Result looks wrong after converting a VCF

Confirm the FASTA you passed to CrossMap is the target assembly. See choosing a reference genome file for matching contig naming.

Free alternatives

Tool	Notes	Source
UCSC liftOver (web)	No install; BED and position-box input	genome.ucsc.edu
CrossMap	GPL v2 or later; many formats including VCF	crossmap.readthedocs.io

FAQ

What is liftOver?

A UCSC program that converts coordinates between genome assemblies using chain files.

What is the UCSC liftOver tool called on the website?

“Lift Genome Annotations”, at genome.ucsc.edu/cgi-bin/hgLiftOver.

Can I liftOver SNPs by rsID?

UCSC does not recommend using liftOver for SNPs with rsIDs.

Is the liftOver command-line tool free?

UCSC states commercial users must purchase a licence for the command-line version. Check the current terms on UCSC’s site.

Sources

UCSC Genome Browser, Lift Genome Annotations: genome.ucsc.edu/cgi-bin/hgLiftOver (read 2026-11-07)
UCSC Genome Browser help, Converting data between assemblies: hgTracksHelp (read 2026-11-07)
UCSC FAQ, Converting genome coordinates between assemblies: FAQdownloads (read 2026-11-07)
CrossMap documentation: crossmap.readthedocs.io (read 2026-11-07)