Install & Compatibility
Where this runs
tested against v3.4.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
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 1.6s · import 0.000s · 23MB
20MB installed
● package 20MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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()
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)
Debug
Known issues
gotchaThe `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.fixEnsure you are installing and importing the correct library for your task: `dockerfile` for parsing Dockerfiles, `docker` for interacting with the Docker daemon.
affects: All versions
breakingBuilding 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.fixInstall 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.
affects: All versions, when building from source
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'dockerfile'
The 'dockerfile' package has not been installed in your Python environment.
fixpip install dockerfile
dockerfile.GoIOError: The file could not be opened: 'path/to/non_existent_Dockerfile'
The Dockerfile path provided to `dockerfile.parse_file()` does not exist or the Python process lacks read permissions for the file.
fixVerify 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: ...
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.
fixReview 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.
Upgrade
Version history
3.4.0latest on PyPI · released Jan 4, 2025
Audit
Dependencies
No dependency data recorded yet.