---
id: copybook
version: "1.0.16"
license: MIT
license_treatment: permissive
maintenance: abandoned
---

# copybook — python copybook parser

License: permissive · Maintenance: abandoned · Downloads: 99.7K/mo

## What it is and what it does

Copybook is a Python parser for VSAM copybook definitions—the schema format used in COBOL and mainframe systems to describe fixed-width record layouts. It reads copybook text (either from a file or string) and builds a tree of field and group objects, exposing metadata like column positions and field lengths. The main use case is extracting that structural information to parse actual fixed-width data files: you define the copybook once, flatten its field list, then use the start positions and lengths to slice and decode each line of raw data according to its PIC clause (numeric, character, signed, etc.).

The package depends only on pyparsing for tokenization and installs with low friction. It supports a range of numeric and character PIC notations, OCCURS and REDEFINES clauses, and groups. However, the project is no longer maintained—the last release was in September 2022 and the repository has seen no commits since May 2023—so it will not receive updates for new Python versions, bug fixes, or unsupported copybook features.

Use it for:

- Parse legacy mainframe data exports in fixed-width format using their original COBOL copybook definitions.
- Extract field positions and data types from copybooks to automate ETL pipelines that consume VSAM or sequential files.
- Convert copybook metadata into column mappings for data analysis or database loading tools.
- Validate or document the structure of fixed-width files by comparing them against their copybook schema.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Copybook parses VSAM copybook definitions and extracts field structure and position information to enable parsing of fixed-width data files.

Yes, if you need to parse VSAM copybooks and can tolerate an abandoned package. The MIT license is permissive, install friction is low, and there are no known vulnerabilities. However, do not expect maintenance, bug fixes, or support for new Python versions. Suitable for stable, low-change integration tasks; risky for production systems requiring ongoing support.

## Install

pip install copybook
uv add copybook
poetry add copybook

## Installing copybook

Before you install: Installation is straightforward with a single runtime dependency (pyparsing). However, the package is abandoned—no releases since 2022-09-15 and no commits since 2023-05-17—so expect no maintenance or bug fixes going forward.

License in practice: MIT license is permissive and poses no restrictions on use, modification, or distribution.

Quickstart:

import copybook
text = """
       01  WORK-BOOK.
        10  TAX-RATE        PIC S9(13)V9(2)
                    SIGN LEADING SEPARATE.
"""
root = copybook.parse_string(text)
list_of_fields = root.flatten()
for field in list_of_fields:
    if type(field)==copybook.Field:
        str_field = line[field.start_pos:field.start_pos+field.get_total_length()]
        print(f"{field.name}: {field.parse(str_field)}")

Verify before relying:

- Whether the package handles all COBOL PIC clause variations encountered in production copybooks
- Compatibility with Python versions beyond 3.7, given the classifier but unspecified requires_python
- Performance characteristics on large copybooks or high-volume fixed-width file parsing

## Package facts

- License: MIT (permissive)
- Python support: unspecified
- Install friction: low
- Maintenance: abandoned
- Downloads: 99.7K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

VSAM copybook parser, fixed-width file parsing, COBOL copybook Python, mainframe data format, copybook field extraction, mainframe-data, cobol-legacy

[View on SkillFed](https://skillfed.io/packages/copybook) · [View on PyPI](https://pypi.org/project/copybook/)