textfsm

library2.1.0pypypi✓ verified 24d ago

TextFSM is a Python module that implements a template-based state machine for parsing semi-structured text into Python tables. Originally developed by Google, it's widely used for extracting structured data from command-line interface (CLI) output of network devices. The library is currently at version 2.1.0 and has a sporadic but active release cadence, focusing on fixes and improvements.

data http-networking devops

pip install textfsm

github ↗package ↗

INSTALL

IMPORT

SIG · TEXTFSM

textfsm

datapythonv2.1.0

Install

1.5s avg

Import

35ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.1.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.036s · 18MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.034s · 19MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

TextFSM

✓ import textfsm

This example demonstrates parsing a simple 'show ip interface brief' style output using an in-memory TextFSM template. It defines values to capture, a 'Start' state to match the header, and a rule to capture data lines into records.

import textfsm import io # Example template string (equivalent to a .textfsm file) template_string = ''' Value Interface (\S+) Value IP_Address (\S+) Value Status (\S+) Value Protocol (\S+) Start ^Interface\s+IP-Address\s+Status\s+Protocol\s*$$ ^${Interface}\s+${IP_Address}\s+${Status}\s+${Protocol} -> Record ''' # Example raw text output to parse raw_text_data = ''' Interface IP-Address Status Protocol GigabitEthernet0/1 192.168.1.1 up up GigabitEthernet0/2 10.0.0.1 up up Loopback0 unassigned up down ''' # Open the template (using io.StringIO for a string, normally a file path) with io.StringIO(template_string) as template_file: # Create a TextFSM object fsm = textfsm.TextFSM(template_file) # Parse the raw text data parsed_data = fsm.ParseText(raw_text_data) # Print headers and data print(fsm.header) for row in parsed_data: print(row) # Expected output: # ['Interface', 'IP_Address', 'Status', 'Protocol'] # ['GigabitEthernet0/1', '192.168.1.1', 'up', 'up'] # ['GigabitEthernet0/2', '10.0.0.1', 'up', 'up'] # ['Loopback0', 'unassigned', 'up', 'down']

textfsm --version

Debug

Known issues

gotchaTextFSM templates use a strict Domain Specific Language (DSL). Incorrect `Value` definitions (e.g., missing regex capture groups, invalid options like `Filldown` without a match), improper `Start` state definitions, or incorrect indentation/blank lines can lead to parsing failures or `textfsm.TextFSMError` exceptions. An empty line after `Value` definitions signals the end of that section.

fix

Carefully review TextFSM template syntax documentation, especially for `Value` options (`Required`, `List`, `Filldown`, `Fillup`) and state transitions. Ensure regex patterns are correctly formatted and include capture groups.

affects: All

gotchaMisunderstanding the `Required` option vs. `Filldown`/`Fillup` can lead to unexpected output. `Required` ensures a record is only emitted if the value is present. `Filldown` propagates the last matched value downwards, while `Fillup` propagates the first matched value upwards to fill preceding empty fields.

fix

Choose the appropriate `Value` option based on your data structure. Use `List` for collecting multiple occurrences of a field within a single record, otherwise, subsequent matches for a `Value` will overwrite previous ones.

affects: All

deprecatedWhile PyPI tags list `Python 2, Python 3` compatibility, modern development and usage of TextFSM (and its ecosystem like `ntc-templates`) strongly recommend Python 3. Older versions like `textfsm==0.4.1` explicitly supported Python 2.x and Python 3.x, but ongoing maintenance primarily targets Python 3 environments.

fix

Migrate any Python 2 TextFSM usage to Python 3. For new projects, always use Python 3.

affects: <= 2.1.0 (Python 2 compatibility)

breakingThe `clitable` module, which provides the `CliTable` utility for loading TextFSM templates from directories, might have had changes in its import path or internal workings in the past. This could lead to `ImportError: cannot import name 'clitable' from 'textfsm'` in projects that directly accessed it.

fix

Ensure you are using the correct import path, typically `from textfsm import clitable` (or directly `textfsm.clitable.CliTable`). Review the official TextFSM GitHub repository for the most up-to-date usage of `CliTable`.

affects: Prior to 2.x (approx.)

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'textfsm'

The textfsm library is not installed in your current Python environment.

fix

pip install textfsm

textfsm.clitable.CliTableError: Template 'my_template.textfsm' not found.

The specified TextFSM template file does not exist, the path is incorrect, or it's not in the search path provided to textfsm.clitable.CliTable.

fix

Ensure the template file exists at the specified path and the 'template_path' parameter for CliTable is correctly set to the directory containing your templates.

ValueError: Invalid template syntax near line X, column Y: ...

The TextFSM template file contains syntax errors, such as incorrect variable definitions, state transitions, or regular expressions.

fix

Carefully review the template file, especially around the indicated line and column, against the TextFSM template syntax documentation and examples.

Upgrade

Version history

2.1.0latest on PyPI · released Apr 17, 2025

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/google/textfsm ↗

packagehttps://pypi.org/project/textfsm/ ↗