gtfparse

Parsing tools for GTF (gene transfer format) files.

Version 3 migration

read_gtf, parse_gtf, and parse_gtf_and_expand_attributes now return pandas DataFrames by default. GTF reading uses PyArrow; attribute processing and writing use pandas. Polars is no longer a required dependency and is imported only for explicit Polars conversion. Ordinary installations need only pandas and PyArrow.

pip install gtfparse
# Optional, for applications that still request Polars frames:
pip install 'gtfparse[polars]'

from gtfparse import read_gtf, write_gtf

df = read_gtf("gene_annotations.gtf")  # pandas.DataFrame
write_gtf(df, "gene_annotations.gtf.gz")

# Requires the optional extra:
polars_df = read_gtf("gene_annotations.gtf", result_type="polars")

Existing pandas and dictionary callers retain their output shape, fixed-column dtypes, attribute handling, filters, converters and progress callbacks. Applications that used the previous default Polars output should add result_type="polars" and install the extra, or use pandas methods. write_gtf accepts either frame type. The legacy parse_with_polars_lazy helper remains an optional adapter: it reads the file eagerly and returns a Polars LazyFrame, as before.

Empty or malformed GTF fields now raise gtfparse.ParsingError, including wrong field counts and invalid numeric fields. Whole comment lines are ignored; literal # inside attributes is preserved. Text and binary streams stay open after parsing, and gzip is detected from its contents.

Reporting parsing progress

Pass progress_callback(stage, completed, total) to read_gtf to connect parsing to your own progress UI. The callback runs synchronously; exceptions from it stop parsing and propagate to the caller. Without a callback, gtfparse does not display a progress bar or add a progress-library dependency.

Stage	Reports
`read`	`(0, None)` before loading/filtering the file; `(rows, rows)` after it succeeds
`attributes`	`(0, rows)`, then every 10,000 rows, then `(rows, rows)`
`convert`	`(0, None)` before output conversion/transforms; `(rows, rows)` after success

Counts refer to rows retained after features filtering, not bytes or overall percentages. None means the total is unknown: loading and conversion expose only stage boundaries, so use an indeterminate indicator during those steps. Attribute expansion is omitted when expand_attribute_column=False. A stage that fails does not emit completion. An empty filtered result is supported; its attributes stage emits a single (0, 0) event. Empty input files raise gtfparse.ParsingError.

For example, with the optional tqdm package installed:

from gtfparse import read_gtf
from tqdm.auto import tqdm

with tqdm(unit="rows") as bar:
    def show_progress(stage, completed, total):
        if stage != bar.desc:
            bar.total = total
            bar.reset()
            bar.set_description_str(stage)
        bar.total = total
        bar.update(completed - bar.n)
        bar.refresh()

    df = read_gtf("gene_annotations.gtf", progress_callback=show_progress)

parse_gtf reports the read stage, parse_gtf_and_expand_attributes reports read and attributes, parse_gtf_pandas reports read and convert, and expand_attribute_strings reports only attributes using the same callback.

Quoted attribute values preserve spaces, semicolons, and apostrophes. Raw attributes (expand_attribute_column=False) retain their original quote marks.

Example usage

Parsing all rows of a GTF file into a Pandas DataFrame

from gtfparse import read_gtf

# returns GTF with essential columns such as "feature", "seqname", "start", "end"
# alongside the names of any optional keys which appeared in the attribute column
df = read_gtf("gene_annotations.gtf")

# filter DataFrame to gene entries on chrY
df_genes = df[df["feature"] == "gene"]
df_genes_chrY = df_genes[df_genes["seqname"] == "Y"]

Getting gene FPKM values from a StringTie GTF file

from gtfparse import read_gtf

df = read_gtf(
    "Transcripts.gtf",
    column_converters={"FPKM": float})

gene_fpkms = {
    gene_name: fpkm
    for (gene_name, fpkm, feature)
    in zip(df["seqname"], df["FPKM"], df["feature"])
    if feature == "gene"
}

Metadata

Release files for gtfparse 3.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for gtfparse 3.0.2
File	Size	Uploaded
gtfparse-3.0.2.tar.gz	144.2 kB	Oct 6, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for gtfparse 3.0.2
File	Interpreter	ABI	Platform	Reset
gtfparse-3.0.2-py3-none-any.whl 24.3 kB Oct 6, 2026	Python 3	none	any	Details

Total release size: 168.5 kB

Release files / gtfparse-3.0.2.tar.gz

Download URL	gtfparse-3.0.2.tar.gz
Size	144.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`33adafa383b71eacd88c92d7a6218ca27790d7f4dfac61ad2aac94fee05c779a`
BLAKE2b-256 checksum How to use checksums	`061f754ba9e1781e3e4b2f42d33cdc9c989f42361d7770888e817fdccaf1bf6b`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.6`

Release files / gtfparse-3.0.2-py3-none-any.whl

Download URL	gtfparse-3.0.2-py3-none-any.whl
Size	24.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`46d5b295b1bf8ae0456e72bbaae1d4007477786365dd7b08e73b1d319fa8084e`
BLAKE2b-256 checksum How to use checksums	`93ad6f2e537f3ac762391f024a87f3d91f5db61bd675fd83f5834adf7380b1ec`
Upload date	Oct 6, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.6`