dockerfile-parse

dockerfile-parse is a small, zero-dependency Python library from the containerbuildsystem project (originally Red Hat) that turns a Dockerfile into a structured, editable model. It exposes a DockerfileParser object whose properties give you a parsed instruction list, the base image, labels, environment variables, and build args as ordinary Python data structures.

Beyond read access, every derived view is writable: assigning to labels, envs, args, or the base image mutates the underlying Dockerfile text in place and reserializes it, so tooling can rewrite Dockerfiles without hand-rolling line manipulation. It has powered container build systems like atomic-reactor and OSBS for years.

What You Get

• A DockerfileParser class that loads a Dockerfile from a path or an in-memory string
• Structured access to each instruction as a dict with its keyword, value, and source line numbers
• Read/write views for labels, environment variables, and build args backed by the raw content
• Base-image inspection and rewriting via the baseimage property, including multi-stage awareness
• Automatic reserialization so edits to the parsed model update the Dockerfile text

Common Use Cases

• Rewriting the FROM base image of a Dockerfile in an automated build pipeline
• Extracting labels and metadata from Dockerfiles for policy or provenance checks
• Injecting or overriding LABEL, ENV, and ARG values during CI image builds
• Auditing a repository of Dockerfiles for their instructions and structure

Under The Hood

Architecture — The public surface is the DockerfileParser class in dockerfile_parse/parser.py (~888 lines), which stores the raw Dockerfile in a cache_content buffer and exposes a structure property that tokenizes the file into a list of instruction dicts (instruction, value, startline, endline, content). Derived views such as labels, envs, args, and baseimage are built on top of structure; the labels/envs/args accessors return KeyValues dict subclasses (Labels, Envs, Args) whose __setitem__/__delitem__ write back through the parser so mutations reserialize the underlying content. Line continuation, comments, and quoting are handled by Context and WordSplitter helpers in util.py.

Tech Stack — Pure Python with zero runtime dependencies (install_requires=[]), supporting Python 3.6+. Packaged with setuptools/setup.py, tested with pytest (pytest.ini, tox.ini), and distributed under the BSD-3-Clause license. An RPM spec file is included for Fedora/RHEL packaging.

Code Quality — The codebase is compact (~1,244 lines across four modules) and battle-tested since 2015 with 35 contributors. A dedicated tests/test_parser.py with fixtures covers parsing and rewriting behavior. The code uses the standard logging module, keeps clear separation between parsing (parser.py) and text utilities (util.py), and is marked Production/Stable.

API Design — The API is idiomatic and low-boilerplate: construct a DockerfileParser, set .content, then read .structure, .labels, or .baseimage. Because the mutable views behave like ordinary dicts and the base image is a simple assignable string, editing a Dockerfile reads like manipulating Python data rather than string surgery, which keeps calling code concise.