Dockerfile Parser

3.4.0 · active · verified Thu Apr 16

The 'dockerfile' Python library (version 3.4.0) provides a high-level representation parser for Dockerfiles, leveraging the official Go parser. It allows programmatic inspection and manipulation of Dockerfile instructions, making it useful for static analysis, linting, or generating Dockerfile content. The library is actively maintained with regular updates.

Common errors

```
ModuleNotFoundError: No module named 'dockerfile'
```
cause The 'dockerfile' package has not been installed in your Python environment.

fix pip install dockerfile
```
dockerfile.GoIOError: The file could not be opened: 'path/to/non_existent_Dockerfile'
```
cause The Dockerfile path provided to `dockerfile.parse_file()` does not exist or the Python process lacks read permissions for the file.

fix Verify that the file path is correct and the Dockerfile exists at that location. Check file permissions to ensure the Python script can read it.
```
dockerfile.GoParseError: Error parsing dockerfile: unexpected token at line X, column Y: ...
```
cause The Dockerfile content provided to `parse_string()` or read by `parse_file()` contains syntax errors that prevent the underlying Go parser from successfully interpreting it.

fix Review the Dockerfile content for compliance with Dockerfile syntax rules. Use a Dockerfile linter (e.g., Hadolint) to identify specific syntax issues and best practice violations.

Warnings

gotcha The `dockerfile` library is a parser for Dockerfiles and is distinct from the `docker` (or `docker-py`) SDK, which is used to interact with the Docker Engine API. Do not confuse the two, as they serve different purposes.
Fix: Ensure you are installing and importing the correct library for your task: `dockerfile` for parsing Dockerfiles, `docker` for interacting with the Docker daemon.
breaking Building the 'dockerfile' library from source (e.g., if prebuilt wheels are not available for your specific platform/Python version) requires a Go compiler to be installed and accessible in your system's PATH.
Fix: Install a Go compiler (e.g., `sudo apt-get install golang` on Debian-based systems) or ensure `pip` is able to download a compatible prebuilt wheel.

Install

pip install dockerfile Install stable version

Imports

parse_string

import dockerfile
commands = dockerfile.parse_string("FROM alpine\nRUN echo hello")

parse_file

import dockerfile
commands = dockerfile.parse_file("path/to/Dockerfile")

Command

from dockerfile import Command
# Used within results of parse_string/parse_file

all_cmds

import dockerfile
known_cmds = dockerfile.all_cmds()

Quickstart

This quickstart demonstrates how to parse a Dockerfile from a file path using `dockerfile.parse_file()`. It then iterates through the parsed commands, printing their type, value, and original line, and shows how to filter for specific command types (e.g., 'RUN').

import dockerfile
import os

# Create a dummy Dockerfile for demonstration
with open("temp_Dockerfile", "w") as f:
    f.write("FROM python:3.9-slim\n")
    f.write("WORKDIR /app\n")
    f.write("COPY requirements.txt .\n")
    f.write("RUN pip install --no-cache-dir -r requirements.txt\n")
    f.write("COPY . .\n")
    f.write("CMD [\"python\", \"app.py\"]\n")

dockerfile_path = "temp_Dockerfile"

# Parse a Dockerfile from a file
try:
    commands = dockerfile.parse_file(dockerfile_path)

    print(f"Parsed {len(commands)} commands from {dockerfile_path}:")
    for cmd in commands:
        print(f"  Command: {cmd.cmd:<10} Value: {cmd.value}, Original: '{cmd.original}'")

    # Example: Find all RUN commands
    run_commands = [c.value for c in commands if c.cmd == 'run']
    print(f"\nRUN commands found: {run_commands}")

finally:
    # Clean up the dummy Dockerfile
    if os.path.exists(dockerfile_path):
        os.remove(dockerfile_path)

view raw JSON →