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 unionis 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__ambiguouscounter.
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.
- Create and activate a Python environment for the project, so the HTSeq version is recorded alongside your analysis.
- Install the package with
pip install HTSeq. - 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. - Check that the command-line script is available by running
htseq-countfrom the shell. If the script is not on your PATH, the documentation givespython -m HTSeq.scripts.countas 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.
- 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).
- Sort paired-end data by read name. The default
-r nameexpects 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. - Choose the strandedness value. Use
-s nofor unstranded libraries,-s yeswhen the first read is on the same strand as the transcript, and-s reversewhen 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. - 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.
- 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.txtHere
-t exonand-i gene_idare the documented defaults (feature type and identifier attribute), written out so the choice is visible in your scripts. - 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_idcounts per transcript identifier instead of per gene .--additional-attr gene_nameadds 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.-asets the minimum alignment quality (MAPQ) and defaults to 10; reads below it are reported in__too_low_aQual.--secondary-alignmentsand--supplementary-alignmentseach takescoreorignore; both default toscore.- 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 yesloses about half the reads on unstranded data. Re-run with-s no, or with-s reverseif 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
chr1and a GTF that names them1will 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.
| Option | Default | Accepted values or note |
|---|---|---|
| -f / --format | sam | sam, bam (deprecated; format is autodetected) |
| -r / --order | name | name, pos |
| --max-reads-in-buffer | 30000000 | integer |
| -s / --stranded | yes | yes, no, reverse |
| -a / --minaqual | 10 | minimum alignment quality (MAPQ) |
| -t / --type | exon | any feature type in the GTF |
| -i / --idattr | gene_id | any GTF attribute |
| -m / --mode | union | union, intersection-strict, intersection-nonempty |
| --nonunique | none | none, all, fraction, random |
| --secondary-alignments | score | score, ignore |
| --supplementary-alignments | score | score, ignore |
| -n / --nprocesses | 1 | integer; one process per input file |
Sources
- HTSeq documentation: Counting reads with htseq-count (accessed 2026-11-17)
Compiled by CASRAI from the sources above. Free to reuse under CC BY 4.0 with attribution.







