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

HTSeq (htseq-count): Install, Options and Output

HTSeq’s htseq-count turns aligned reads and a GTF into gene counts: install, strandedness and overlap settings, special counters and troubleshooting.

Written and maintained by CASRAI Editorial Board

Published

On this page

HTSeq is a Python package for working with high-throughput sequencing data, and its htseq-count script is the part most researchers use: it takes aligned reads (SAM or BAM files) plus a GTF annotation and reports how many reads or read pairs fall on each gene, exon or other feature. The result is a table of raw counts per feature and sample, the usual input for RNA-seq differential expression, together with a short set of special counters that show what happened to reads that were not counted.

What HTSeq is used for in research

In an RNA-seq workflow, an aligner such as STAR or HISAT2 places reads on a reference genome, and a counting step then converts those placements into one number per gene per sample. htseq-count does the counting step. It overlaps each aligned read with the features in a GTF file, decides which feature (if any) the read belongs to, and writes the tally. Our RNA-seq steps guide shows where counting sits between alignment and statistical testing, and the STAR aligner guide covers the alignment step that comes before it.

The package is described in the paper by Anders, Pyl and Huber, published in Bioinformatics in 2015 (doi:10.1093/bioinformatics/btu638). The documentation is hosted at htseq.readthedocs.io and the package is distributed on PyPI as HTSeq.

Three things are worth knowing before you run it, because they change the numbers in your matrix more than most other options do:

  • Strandedness. The default is -s yes. The documentation warns: “Make sure to set the option –stranded=no unless you have strand-specific data!” Running unstranded data with the default discards about half the reads.
  • The overlap mode. The default -m union is the mode the documentation recommends for most uses.
  • The treatment of ambiguous reads. By default (--nonunique none) a read that could belong to several features is counted for none of them and appears only in the __ambiguous counter.

The counts htseq-count produces are raw counts. They are not normalised for gene length or sequencing depth; for the difference between raw counts, TPM and FPKM see TPM vs FPKM vs raw counts.

How to install or access HTSeq

The official installation page gives pip install HTSeq as the standard route. HTSeq depends on NumPy and Pysam; matplotlib is needed only for the plotting and quality-assessment script htseq-qa. If pip has to build the package from source, Cython and SWIG are required as well. The PyPI listing for HTSeq version 2.1.2 declares Python 3.10 or later as the supported interpreter, and the installation page lists Linux and macOS and states that Windows is not supported.

  1. Create and activate a Python environment for the project, so the HTSeq version is recorded alongside your analysis.
  2. Install the package with pip install HTSeq.
  3. Check that the import works. The installation page asks you to run python -c "import HTSeq" from a directory that does not contain a folder called HTSeq, otherwise Python imports the local folder instead of the installed package.
  4. Check that the command-line script is available by running htseq-count from the shell. If the script is not on your PATH, the documentation gives python -m HTSeq.scripts.count as the equivalent invocation.

Record the version string with your results. The version that counted your reads is part of the method, and option defaults have changed across releases (the -f input-format option, for example, is deprecated in the current documentation because the format is auto-detected).

How to count reads per gene with htseq-count step by step

The documented usage is:

htseq-count [options] alignment_files gtf_file

Several alignment files can be given in one call, and a single dash reads alignments from standard input. The option -n sets the number of processes; the documentation notes that the parallelism is one process per input file, with a default of 1.

The steps below are an illustrative command sequence built only from options listed in the current documentation. File names are placeholders, and the strandedness value must be replaced with the one that matches your library preparation.

  1. Align the reads and keep a BAM file. Any aligner that writes SAM or BAM works. If you used STAR, it can also write its own per-gene counts (see the alternatives section).
  2. Sort paired-end data by read name. The default -r name expects all alignments of a read pair in adjacent records. The documentation recommends unsorted (name-ordered) BAM files for paired-end data and says that if you get odd results you should sort by name and try again: samtools sort -n -o sample.name.bam sample.bam.
  3. Choose the strandedness value. Use -s no for unstranded libraries, -s yes when the first read is on the same strand as the transcript, and -s reverse when the second read is. Your library-prep documentation tells you which applies; the STAR guide linked above shows the same mapping for its per-gene columns.
  4. Confirm the annotation matches the genome. Use the GTF from the same assembly and the same chromosome naming as the alignment (see the troubleshooting section). The GTF vs GFF3 comparison explains why the file format matters for the feature and identifier attributes.
  5. Run the count. For a reverse-stranded library counting exons grouped by gene identifier:
    htseq-count -r name -s reverse -t exon -i gene_id -m union --nonunique none sample.name.bam annotation.gtf > sample.counts.txt

    Here -t exon and -i gene_id are the documented defaults (feature type and identifier attribute), written out so the choice is visible in your scripts.

  6. Repeat for every sample and merge the per-sample files by feature name into one matrix before statistical analysis. Keep the command line with the results.

Variations the documentation supports

  • --idattr transcript_id counts per transcript identifier instead of per gene .
  • --additional-attr gene_name adds a column of extra annotation attributes; repeat the option for each attribute.
  • --feature-query 'gene_name == "ACTB"' restricts counting to features that satisfy the expression.
  • -a sets the minimum alignment quality (MAPQ) and defaults to 10; reads below it are reported in __too_low_aQual.
  • --secondary-alignments and --supplementary-alignments each take score or ignore; both default to score.
  • the documentation lists tsv, csv, mtx, h5ad and loom as output formats (option -c), which is useful when the matrix feeds a single-cell toolchain.

The data table at the end of this page lists the main options with their documented defaults and accepted values.

Choosing the overlap and ambiguity settings

The two settings that most affect which reads count are the overlap mode (-m) and the treatment of ambiguous reads (--nonunique). The documentation recommends union for most uses, and the other modes are intersection-strict and intersection-nonempty. The decision table below summarises the documented behaviour of the four --nonunique values.

–nonunique value What happens to an ambiguous read Effect on the totals
none (default) Counted only in __ambiguous, for no feature Feature counts sum to less than the number of reads
all Counted for every feature it was assigned to Column sums can exceed the number of reads
fraction Split evenly, so a read shared by three features adds one third to each Totals equal the number of reads or read pairs
random Assigned at random with equal probability to one of its features Totals equal the number of reads or read pairs

Whichever you choose, apply it to every sample in the study and state it in the methods. Mixing settings across samples makes the columns of the matrix non-comparable.

How to read the output

The output has one line per feature, with the feature identifier and its count, and one line per special counter after the features. The special counters start with two underscores so they cannot be confused with gene identifiers. They are the quickest quality check on a run, because they account for every read that was not assigned to a feature.

Counter Meaning in the documentation
__no_feature No feature was found for the read or read pair
__ambiguous More than one feature was possible, so the read is not counted (unless --nonunique all is used)
__too_low_aQual Skipped because its alignment quality is below the -a threshold
__not_aligned The record in the SAM or BAM file carries no alignment
__alignment_not_unique More than one reported alignment, detected through the NH tag

A practical way to read a run is to compare the special counters with the total of the feature lines. A large __no_feature value relative to the feature counts points at a mismatch between alignments and annotation or at the wrong strandedness setting, covered next. A large __ambiguous value points at overlapping gene models or at an annotation file in which identifiers are not unique. A large __alignment_not_unique value reflects multi-mapping reads, which is a property of the library and the reference rather than of the counting options.

The feature lines are raw counts. Before comparing genes within a sample, or samples with different sequencing depth, remember that differential expression tools generally expect the raw counts, not normalised values (see the comparison linked in the first section).

Troubleshooting HTSeq

The documentation’s FAQ lists the usual causes when most reads fall into __no_feature, and the same checks resolve most failed runs.

Most reads are counted as __no_feature

  • Wrong strandedness. The default -s yes loses about half the reads on unstranded data. Re-run with -s no, or with -s reverse if your library is reverse-stranded.
  • Different reference assemblies. The GTF coordinates must come from the same assembly as the alignments.
  • Mismatched chromosome names. A BAM file that names chromosomes chr1 and a GTF that names them 1 will not overlap.

Many reads are counted as __ambiguous

The FAQ warns that GTF files from the UCSC Table Browser often have a gene_id identical to the transcript_id, which makes many reads look ambiguous. Use an annotation file whose gene_id groups the transcripts of a gene.

Paired-end data gives strange results or high memory use

With position-sorted paired-end data (-r pos), mates that have not yet been matched are held in memory. The --max-reads-in-buffer option limits this buffer and defaults to 30,000,000; the documentation notes that raising it uses more memory. The simpler remedy given in the documentation is to sort the BAM file by read name with samtools sort -n and run again with the default -r name.

The command or the import is not found

If htseq-count is not on your PATH, call it as python -m HTSeq.scripts.count. If import HTSeq fails right after installing, repeat the import test from a different directory, as the installation page advises.

Free alternatives to HTSeq

HTSeq is free software distributed on PyPI. Counting reads per gene can also be done by other tools; the table lists the two that this site already documents, with only what those pages state.

Tool What it does Where to read more
featureCounts Counting component of the Subread software family, also available in R through the Rsubread package; takes alignment files plus annotation and reports counts per target featureCounts guide
STAR gene counts The STAR aligner can write per-gene counts during alignment in ReadsPerGene.out.tab; a read is counted if it overlaps at least one nucleotide of one and only one gene, which matches the htseq-count defaults STAR aligner guide

Whichever counting tool you choose, keep the same one for every sample in a study and record its version and settings, because strandedness, overlap and ambiguity rules differ between tools and between interfaces of the same tool.

Sources

Data: htseq-count main options, defaults and accepted values

The main htseq-count command-line options with their documented default and accepted values, compiled from the HTSeq documentation page for htseq-count. Intended as a quick reference for choosing settings in an RNA-seq read-counting step.

htseq-count main options, defaults and accepted values
OptionDefaultAccepted values or note
-f / --formatsamsam, bam (deprecated; format is autodetected)
-r / --ordernamename, pos
--max-reads-in-buffer30000000integer
-s / --strandedyesyes, no, reverse
-a / --minaqual10minimum alignment quality (MAPQ)
-t / --typeexonany feature type in the GTF
-i / --idattrgene_idany GTF attribute
-m / --modeunionunion, intersection-strict, intersection-nonempty
--nonuniquenonenone, all, fraction, random
--secondary-alignmentsscorescore, ignore
--supplementary-alignmentsscorescore, ignore
-n / --nprocesses1integer; one process per input file

Sources

Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.

Follow CASRAI

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

Ask CASRAI · free to try

Ask about HTSeq (htseq-count): Install, Options and Output

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 →