# Ensembl BioMart Export Formats: Which File Type Should You Choose Ensembl BioMart export formats fall into three families. Tabular formats (TSV, CSV, XLS, and HTML) return attributes such as identifiers, gene symbols, coordinates, and orthologs (the matched genes in other species) as rows and columns. FASTA returns biological sequences. Coordinate formats (GTF, GFF3, and BED) return genomic features that annotation tools and genome browsers read directly. That is the one-sentence difference: tabular files describe features, FASTA files carry sequence, and coordinate files carry position. The rule of thumb is to pick the format your next program reads natively. Choose TSV for R, Python, and command-line work. Choose CSV or XLS only when a spreadsheet is the final destination. Choose FASTA for BLAST, alignments, and search databases. Choose GTF for RNA-seq quantification. Choose BED for interval arithmetic and custom genome browser tracks. BioMart is the bulk query interface built into Ensembl, the reference database for genome annotation. It is also a portable pattern used by other resources. A study of access systems for the PeptideAtlas proteomics repository implemented BioMart as one of three common mechanisms for reaching web-accessible research data, and noted that projects often provide several access points so users can pick the simplest effective route [1]. PRIDE, another proteomics resource, supports federated BioMart queries, meaning one query that spans multiple databases, joining proteomics identifications with Ensembl, Reactome, and UniProt [2]. Once you understand the export formats at Ensembl, the same knowledge transfers to those other BioMart servers. ## How Ensembl BioMart Export Works Learning how to use Ensembl effectively means matching the tool to the question. The genome browser answers single-locus questions. BioMart answers batch questions: give me every gene on chromosome 22 with a UniProt ID, the cDNA of these 500 transcripts, or the coordinates of all mouse orthologs of these human genes. ### The Four Steps of a BioMart Query ![Flowchart of a BioMart session: choose database, dataset, filters, attributes, check row count, then export and save the XML query.](/article-images/illustrations/ensembl-biomart-export-formats-query-to-export.webp) Point your browser to www.ensembl.org/biomart. A session has four steps, shown as panels or tabs. First, choose the database, such as Ensembl Genes, Ensembl Variation, or Ensembl Regulation, or one of the separate Ensembl Genomes marts covering plants, fungi, metazoa, protists, and bacteria. The database name includes the release number, for example Ensembl Genes 113. Second, choose the dataset, which is the species and genome build, such as Homo sapiens genes (GRCh38). Third, set filters, which restrict what comes back. Fourth, choose attributes, which are the columns you want. Filters accept pasted lists and structured values. You can paste 200 HGNC symbols (the standard human gene names) into the symbol filter, enter a chromosomal region such as 7:55000001-56000000, restrict to protein-coding genes by biotype, require an ortholog in a target species, or filter by Gene Ontology terms, the controlled vocabulary of gene functions. A filter that matches nothing is the most common cause of an empty export, so check the result count before building a complicated query. Attribute categories decide which export formats the menu will offer. Gene details and external references such as HGNC symbols, UniProt protein IDs, and RefSeq transcript IDs produce tabular output. The sequences category, with record types such as cDNA, peptide, coding sequence, untranslated regions, and genomic sequence with a configurable flank, enables FASTA. Structure information, such as exon coordinates and transcript structure, enables GTF, GFF3, and BED. Homolog attributes return one block of columns per comparison species, including dN and dS (the rates of nonsynonymous and synonymous substitution) and an orthology confidence score. ### The Results Page, Where the Format Choice Lives Click Results and BioMart reports the number of matching rows before you commit to an export. The results page holds the format dropdown, a preview of the first rows, a choice between a small preview and the full export, an only-unique-results checkbox, and a compress checkbox that returns the file as a gzip archive, a standard compressed format. Check the row count first. A query returning two million rows will not fit in a browser preview, may time out, and should be split by chromosome or moved to the URL API described later. ### BioMart and the Ensembl Genome Browser Most [Ensembl genome browser](/blog/guides/ensembl-genome-browser) tutorials begin with the search box and the location view, which is the right tool when you want to inspect one gene, its transcripts, and its regulatory context. BioMart is the right tool when the answer needs thousands of rows. The two connect in both directions: a BED export from BioMart can be uploaded to a genome browser as a custom track, so a batch result becomes a visual one. ## Ensembl BioMart Export Formats Compared This table is the core decision aid. Match the row to the program that will open the file next. | Format | What it holds | Best for | Typical readers | Main drawback | |, - |, - |, - |, - |, - | | HTML | A formatted table rendered in the browser | Quick visual checks of small results | Your eyes | Markup mixed with data, unusable in scripts, heavy for large results | | TSV | Plain-text table, tab-separated, one header row | Analysis pipelines | R, pandas, cut, awk, most languages | Not double-click friendly for spreadsheet users | | CSV | Plain-text table, comma-separated | Handoffs to Excel | Excel, read.csv | Excel silently converts gene symbols and long numbers | | XLS | An Excel workbook | Small curated tables for human editors | Excel only | Binary, invisible to text tools and most scripts | | FASTA | Sequences with header lines | BLAST, alignment, search databases | BLAST, aligners, motif tools | Attributes survive only in the header line | | GTF | Gene structures, nine tab-delimited columns, 1-based | RNA-seq counting and transcript assembly | featureCounts, HTSeq, StringTie, STAR | Contains only your filtered subset, tied to one release | | GFF3 | Gene structures with parent-child hierarchy | Genome browsers, annotation pipelines | Genome browsers, annotation tools | Fewer RNA-seq tools accept it natively | | BED | Minimal intervals, 0-based half-open | Interval arithmetic, custom tracks | bedtools, UCSC custom tracks | Carries almost no annotation | Three notes on the menu itself. The format list changes with your attribute selection, so FASTA, GTF, GFF3, and BED appear only when the query supports them. Depending on the Ensembl release, the menu can also list sequence-record formats such as INSDSeq, EMBL, and GenBank, which wrap a sequence together with structured metadata for exchange with [nucleotide sequence](/knowledge/molecular-biology/nucleotide-sequence) databases. The download arrives as plain text named mart_export by default, so rename it with a meaningful name such as tp53_homologs.tsv the moment you save it. ## Tabular Export Formats: HTML, TSV, CSV, and XLS Tabular exports return one row per result and one column per selected attribute, in the order you selected them. They are the workhorse formats, and the differences among them are about who or what reads the file. ### HTML: For Looking, Not for Pipelines HTML renders the result as a formatted page in the browser. It is the right choice for a 20-row sanity check or for pasting a small table into a report. It is the wrong choice for anything else. HTML mixes data with markup, so scripts cannot read it without fragile parsing, and a large result can slow or crash the browser tab. If you catch yourself copying HTML output into Excel by hand, switch to CSV. ### TSV: The Default and Usually the Right Answer TSV, tab-separated values, is a plain-text table where a tab character separates columns and the first line names them. BioMart makes TSV the default, and that default is usually correct. Tabs almost never occur inside gene descriptions, so the file parses cleanly without quoting rules. Read it directly in R, Python, or the shell: ```r genes <- read.delim("mart_export.tsv") ``` ```python import pandas as pd genes = pd.read_csv("mart_export.tsv", sep="\t") ``` ```bash cut -f1,3 mart_export.tsv | head ``` Two habits to build. First, missing values usually arrive as empty cells, so decide how your script treats blanks before merging tables. Second, attributes with one-to-many relationships multiply rows, a behavior covered in the mistakes section below. ### CSV: For Spreadsheet Handoffs CSV, comma-separated values, is a plain-text table separated by commas. Its advantage is that Excel opens it by double-click. Its disadvantage is the same double-click. Excel guesses column types, and it guesses wrong for genomics in two specific ways. Gene symbols that look like dates, such as SEPT1 or MARCH1, get converted into date values. Long numeric identifiers get rounded and displayed in scientific notation, which destroys them. Both changes are silent and become permanent once the file is saved. If the file must pass through Excel, have the recipient import it as text: use the data import wizard and set every column to Text, or paste through a plain-text editor first. If the spreadsheet is only a container for later scripting, send TSV instead and let R or pandas read it with explicit column types. ### XLS: When a Person in Excel Is the Destination XLS is an Excel workbook, a binary format that Excel opens directly. Choose it for a small, curated table that a human will read and edit, such as a candidate gene list for a meeting. XLS is invisible to grep, awk, and most scripting languages, so never make it the archival copy. Keep the TSV as the canonical file and treat the workbook as a disposable view. ## FASTA: Exporting Sequences FASTA is the text format for biological sequences. Each record starts with a header line beginning with the greater-than symbol, followed by the sequence in single-letter codes, wrapped at a fixed line length, conventionally 60 characters. BioMart produces FASTA when your attributes come from the sequences category. The sequences category offers several record types, and that choice matters more than any format setting: - cDNA, the mature transcript sequence, for transcript-level searches. - Peptide, the protein sequence, for protein searches and domain work. - Coding sequence (CDS), the translated portion only. - 5' and 3' untranslated regions (UTRs), for regulatory element searches. - Genomic sequence with a configurable flank, for promoter and flanking-region studies. The FASTA header carries the identifiers you selected as attributes. If you select Ensembl Gene ID, Ensembl Transcript ID, and gene start and end coordinates, those values appear in the header. Write your downstream parser against the attributes you actually selected, and include every identifier you need, because the header is the only place attributes survive in FASTA. Typical uses include building a BLAST database (the standard sequence similarity search tool) for a gene family, aligning orthologs across species, extracting promoter regions for motif discovery, and preparing custom protein search databases. Building tailored sequence databases to improve search engine results is established practice in proteomics, where tools such as PRIDE's Database on Demand construct custom databases for exactly that purpose [2]. A BioMart peptide export serves the same goal on the Ensembl side. Worked example: to retrieve peptides for a list of human genes, paste the gene symbols into the filter, open Attributes, choose the sequences category, select Peptide together with the Ensembl Gene ID and HGNC symbol, set the format to FASTA, and export. Feed the file to BLAST+: ```bash makeblastdb -in family_peptides.fa -dbtype prot -out family_db blastp -query candidates.fa -db family_db -outfmt 6 -out hits.tsv ``` One record per sequence is the rule. A gene with three transcripts produces three cDNA records, so decide whether your question is gene-level or transcript-level before you export. ## GTF, GFF3, and BED: Exporting Coordinates and Gene Structures These three formats describe where features sit on a genome. They differ in how much annotation they carry and which tools accept them. All three appear in the format menu when your attribute selection includes structure information such as exon coordinates. ### GTF: The RNA-seq Annotation Format GTF, Gene Transfer Format, is a tab-delimited text format with nine columns per feature line: 1. Sequence name, the chromosome or scaffold. 2. Source, the annotation project. 3. Feature type, such as gene, transcript, exon, or CDS. 4. Start coordinate, 1-based and inclusive. 5. End coordinate, inclusive. 6. Score, usually a placeholder period. 7. Strand, plus or minus. 8. Frame, the reading phase for CDS features, otherwise a period. 9. Attributes, key-value pairs such as gene_id and transcript_id. GTF is the standard annotation input for RNA-seq (RNA sequencing) tools. featureCounts and HTSeq count reads per gene from a GTF. StringTie assembles transcripts against a GTF. STAR uses a GTF to build its splice junction tables. If your next step is quantification, GTF is the export to pick. A BioMart GTF export contains only the features that pass your filters. That is a feature, not a bug, when you want a pilot annotation for one chromosome or a gene panel. For a full analysis, download the complete GTF for your release from the Ensembl FTP site instead, so that read counts cover all genes and no feature is silently missing. ### GFF3: The Annotation Format for Browsers and Pipelines GFF3, Generic Feature Format version 3, also uses nine tab-delimited columns with 1-based coordinates. It differs from GTF in its attribute syntax, key=value pairs, and its support for explicit parent-child relationships through ID and Parent attributes, plus directive lines that begin with two hash characters. Genome browsers and annotation pipelines are its natural readers. Choose GFF3 when the destination is a browser track or an annotation tool that asks for GFF3, and GTF when the destination is an RNA-seq counter. ### BED: Minimal Intervals for Interval Arithmetic BED, Browser Extensible Data, is the most minimal of the three. The first three columns are required: 1. Chromosome. 2. Start, 0-based. 3. End, exclusive, meaning the interval stops just before this coordinate. Optional columns add a name, a score, and a strand. Because BED carries little beyond coordinates, it is the interchange format for interval arithmetic. bedtools, the standard toolkit for interval operations, reads it. The UCSC Genome Browser accepts it as a custom track, and the Ensembl browser accepts uploaded data files for display alongside its own annotations. The coordinate convention is the trap. GTF and GFF3 count bases from 1 and include both ends. BED counts from 0 and excludes the end. The same single base is written as 1000 to 1001 in BED and as 1001 to 1001 in GTF-style coordinates. Converting by hand is how off-by-one errors enter pipelines, so convert with a tool and verify against a gene whose position you know. Worked example: to find ChIP-seq peaks (measured protein-DNA binding sites) that fall in promoters, the regions upstream of each transcription start site, export gene coordinates as BED, build promoter windows, and intersect: ```bash bedtools intersect -a peaks.bed -b promoters.bed -wa -wb > peak_promoter_overlaps.txt ``` ## How to Choose: The Criteria That Decide ![Decision path asking what opens the file next, leading to TSV, CSV or XLS, FASTA, GTF, or BED as the export to pick.](/article-images/illustrations/ensembl-biomart-export-formats-format-triage.webp) Four criteria separate the ensembl biomart export formats options in practice. **Fidelity.** TSV preserves every attribute you selected. FASTA preserves sequence and reduces everything else to a header line. GTF and GFF3 preserve structure and a fixed attribute vocabulary. BED preserves coordinates and almost nothing else. HTML preserves presentation. Pick the format that loses the least information your question needs. **Toolchain.** The best Ensembl BioMart export format is decided by the first program that opens the file. R and pandas read TSV and CSV. BLAST and aligners read FASTA. RNA-seq counters read GTF. bedtools and genome browsers read BED. Excel reads CSV and XLS. Fighting a tool with the wrong format costs more time than re-running the query. **Scale.** HTML degrades first, because the browser must render every row. Plain-text formats scale to large exports, especially with the compress checkbox. For very large jobs, split the query by chromosome or move it to the URL API. **Destination.** A human reader in Excel points to CSV or XLS. A script points to TSV. A pipeline points to FASTA, GTF, or BED. HTML points nowhere downstream. No format wins everywhere. That conclusion matches what access-system research finds generally: comparisons of data access mechanisms, including BioMart, conclude that each suits particular uses and involves tradeoffs [1]. Decide by the next step in your workflow, not by habit. ## Worked Scenarios ### Annotate a Differential Expression Gene List You have 500 Ensembl gene IDs from an RNA-seq analysis of genes whose expression changed between conditions, and you need symbols, biotypes, coordinates, and descriptions. Filter on the Ensembl Gene ID list, select the attributes, and export TSV. In R, merge on the gene ID column: ```r annot <- read.delim("gene_annotation.tsv") merged <- merge(results, annot, by.x = "gene_id", by.y = "Ensembl.Gene.ID") ``` R replaces spaces in the header with dots, hence Ensembl.Gene.ID. If you also want GO terms, run that as a second query, because GO attributes multiply rows, then aggregate per gene. ### Hand a Table to a Spreadsheet User A collaborator will curate 200 candidate genes in Excel. Export CSV, and tell them to import with every column set to Text so symbols like SEPT1 and MARCH1 survive as text. If they only need to read the file, XLS is fine. Keep the TSV as your own canonical copy. ### Build a BLAST Database for a Gene Family You want all known members of a transporter family across several species. Query each species dataset with the family or ortholog filters, select peptide sequences together with gene and protein identifiers, and export FASTA. Concatenate the files and build the database: ```bash cat human.fa mouse.fa zebrafish.fa > family_peptides.fa makeblastdb -in family_peptides.fa -dbtype prot -out family_db ``` ### Make a Subset Annotation for an RNA-seq Pilot For a pilot run on chromosome 22, filter to that chromosome and the protein-coding biotype, choose structure attributes, and export GTF. Point featureCounts at it for a quick count. For the publishable analysis, switch to the full-release GTF from the Ensembl FTP site so counts are comparable across all genes. ### Intersect ChIP-seq Peaks with Promoters Export gene coordinates as BED, create promoter windows upstream of each transcription start site with bedtools flank or a short script, and intersect with your peak file using bedtools intersect. Verify one known gene by eye to confirm the strand and the 0-based convention before trusting the output. ### Cross-Resource Annotation with Federated Queries When a question spans resources, BioMart can sometimes answer it in one query. The PRIDE proteomics resource demonstrated federated BioMart queries that integrate proteomics identifications with Ensembl, Reactome, and UniProt [2]. Before writing custom identifier-mapping scripts, check whether both resources expose BioMart and whether a federated query covers the columns you need. ## Reproducible Exports: The XML Button, the URL API, and biomaRt A point-and-click export is hard to reproduce exactly, because the query lives only in your browser session. BioMart gives you three ways to pin it down. First, the XML button on the results page shows the full query as an XML document. Save it. Anyone can rerun the query by submitting that XML to the martservice endpoint, the HTTP address that accepts BioMart queries, over the web: ```bash curl "http://www.ensembl.org/biomart/martservice?query=PASTE_THE_XML_HERE" ``` The response comes back in the format you selected. This works because BioMart projects deliberately expose both interactive web pages and web service access, so scripts can reach the same data as point-and-click users [1]. Second, the biomaRt package from Bioconductor, the R software project for [computational biology](/knowledge/bioinformatics/vaccinomics-and-the-future-of-personalized-vaccines), runs the same queries inside R and returns a data frame: ```r library(biomaRt) ensembl <- useEnsembl(biomart = "genes", dataset = "hsapiens_gene_ensembl") getBM(attributes = c("ensembl_gene_id", "hgnc_symbol", "chromosome_name", "start_position", "end_position"), filters = "hgnc_symbol", values = c("TP53", "BRCA1"), mart = ensembl) ``` Third, pin the release. The database name carries the release number, and annotation changes between releases as genes are added, merged, or retired. Record the release, the dataset, the filters, the attributes, and the format with every export. For work on the older human reference build, use the GRCh37 archive site at grch37.ensembl.org, because the two human reference genome builds (GRCh37 and GRCh38) place the same gene at different coordinates, and mixing them silently corrupts any downstream join. ## Common Mistakes and Limitations 1. **Row explosion from one-to-many attributes.** A gene with five GO terms returns five rows when GO is selected, and the same happens with orthologs, protein domains, and microarray probes. The only-unique-results checkbox removes exact duplicate rows only. Aggregate per gene afterward, for example with aggregate in R or groupby in pandas. 2. **Excel corrupting identifiers.** Opening a CSV in Excel converts date-like gene symbols such as SEPT1 and MARCH1 into dates and rewrites long numeric identifiers in scientific notation. The damage is silent and saved with the file. Import columns as text, or keep the data out of Excel entirely. 3. **Coordinate convention errors.** BED is 0-based with an exclusive end. GTF and GFF3 are 1-based and inclusive. An interval copied between the two without conversion shifts by one base. Convert with a tool and verify against a known gene. 4. **Mixing genome builds.** The main Ensembl site serves GRCh38, and the GRCh37 archive serves the older build. Pin one build across every input file in a project. 5. **Wrong dataset or release.** Species datasets sit next to each other in the menu, and releases change annotation. Record the release number with every export and use archive sites for historical queries. 6. **Using BioMart for whole-genome files.** BioMart is built for filtered subsets. For the complete GTF, GFF3, or genome FASTA, the Ensembl FTP site is the better source and is faster for bulk downloads. 7. **Losing the query.** If you do not save the XML or the biomaRt code, the query is gone when the tab closes. Save it before you export, not after. 8. **Browser timeouts on large exports.** A multi-million-row query can fail in the browser. Split it by chromosome, use the compress option, or submit it through the martservice URL. 9. **Parsing FASTA headers too loosely.** The header layout depends on the attributes you selected. Scripts written against one export break when someone changes the attribute list. Include every needed identifier as an attribute and parse the header against that list. One boundary to keep in mind: BioMart returns annotation, identifiers, sequences, and coordinates. Interactive, single-gene exploration belongs in the Ensembl genome browser, and bulk reference files belong on the FTP site. BioMart covers the middle ground of filtered, structured queries, and it performs best when the export format matches the next program in your pipeline. ## Frequently Asked Questions ### What is the default export format in Ensembl BioMart? TSV, tab-separated values, is the default format. It is a plain-text table with one header row and one row per result, and it is the safest choice for R, Python, and command-line work. ### Which Ensembl BioMart export format should I use for Excel? CSV or XLS for a table headed to a spreadsheet. Have the recipient import CSV columns as text so gene symbols are not converted to dates. If the table will return to a script later, send TSV instead. ### How do I export sequences from Ensembl BioMart? Open Attributes, choose the sequences category, pick a record type such as cDNA, peptide, or coding sequence, then set the output format to FASTA before you export. The FASTA header carries the identifiers you selected as attributes. ### What is the difference between GTF and GFF3 exports? Both describe gene structures in nine tab-delimited columns with 1-based coordinates. GTF is the standard input for RNA-seq counting and assembly tools, while GFF3 is more common in genome browsers and annotation pipelines. ### Can I automate Ensembl BioMart exports? Yes. Click the XML button to capture the query, then submit it to the BioMart martservice URL with curl, or run the same query in R with the biomaRt package from Bioconductor. ### Why does my BioMart export have more rows than genes? Attributes with one-to-many relationships, such as GO terms or orthologs, create one row per pairing. The unique results option removes only exact duplicates, so aggregate rows per gene in R or Python afterward. ## Sources 1. [Interfaces to PeptideAtlas: a case study of standard data access systems.](https://pubmed.ncbi.nlm.nih.gov/22941959/) 2. [PRIDE and "Database on Demand" as valuable tools for computational proteomics.](https://pubmed.ncbi.nlm.nih.gov/21063943/)