# How to Build an Image with a Custom Dockerfile Path Using apple/container > Learn to build Docker images with custom Dockerfile paths using apple/container. Use the -f or --file flag with container build for flexible builds. Get started today. - Repository: [Apple/container](https://github.com/apple/container) - Tags: how-to-guide - Published: 2026-07-05 --- **Use the `-f` or `--file` flag with `container build` to specify any Dockerfile location, followed by your desired image tag and the build context directory.** The `apple/container` tool constructs OCI-compatible images using a lightweight builder VM running BuildKit. While the default behavior searches for a `Dockerfile` in the root of your build context, you can build an image with a custom Dockerfile path by explicitly pointing to any file location on disk using command-line flags. ## Understanding the Build Context and Dockerfile The `container build` command requires three distinct pieces of information: - **Tag**: The name and optional version tag for your output image (`-t` or `--tag`) - **Dockerfile path**: The specific file containing build instructions (`-f` or `--file`) - **Build context**: The directory that serves as the root for `COPY` and `ADD` operations (last positional argument) According to the source documentation in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (lines 149-171), when you omit the `-f` flag, the builder searches for a file named `Dockerfile` first, falling back to `Containerfile` if not found. Providing the `-f` flag overrides this default discovery mechanism. ## Using the -f/--file Flag for Custom Paths The `-f` flag accepts any relative or absolute path to a Dockerfile, allowing you to maintain multiple build variants (such as production, development, and test configurations) within the same repository without renaming files. ### Dockerfile in a Subdirectory When your Dockerfile lives in a subdirectory rather than the repository root, specify the relative path: ```bash container build -f docker/Dockerfile.prod -t my-app:prod . ``` This example, referenced in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 170), uses `docker/Dockerfile.prod` as the instruction set while maintaining the current directory (`.`) as the build context. ### Separating Context and Dockerfile You can completely separate the Dockerfile location from your source files. This is useful when organizing dockerfiles in a dedicated directory while keeping application code elsewhere: ```bash container build -f dockerfiles/Dockerfile -t my-service:latest src ``` Here, the builder receives only the contents of `src/` as the build context, while reading instructions from `./dockerfiles/Dockerfile`. The [`docs/start-here.md`](https://github.com/apple/container/blob/main/docs/start-here.md) tutorial (lines 120-156) demonstrates this pattern for organizing complex projects. ### Using Absolute Paths The `-f` flag also accepts absolute paths, enabling you to reference Dockerfiles stored outside your immediate project tree: ```bash container build -f /opt/build/Dockerfile -t external-image:1.0 . ``` This flexibility allows centralized management of common Dockerfiles across multiple projects. ## How the Builder Processes Custom Paths According to the implementation details in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 69-71), `apple/container` launches a lightweight builder VM that runs BuildKit. The tool transmits the build context as a tarball to the builder and reads the Dockerfile from your specified path. Whether you provide a relative path like `docker/Dockerfile.prod` or an absolute path like `/Users/me/projects/Dockerfile`, the builder locates and parses that file while treating the final positional argument as the root for all file copy operations. ## Complete Command Syntax Reference The full command structure follows this pattern: ```bash container build -f -t : ``` Key implementation notes from the source: - The Dockerfile path can be anywhere on disk—relative or absolute - The build context determines what files are available to `COPY` and `ADD` instructions - Files referenced by `COPY` must exist within the build context directory structure ## Summary - **Use `-f `** to specify any Dockerfile location, overriding the default search for `Dockerfile` or `Containerfile` in the context root. - **Provide the build context** as the final positional argument (typically `.` for current directory or a specific subdirectory like `src/`). - **Support for multiple variants**: Keep separate Dockerfiles (e.g., `Dockerfile.dev`, `docker/Dockerfile.prod`) in the same repository without conflicts. - **Path flexibility**: Accepts both relative paths (resolved against current working directory) and absolute paths anywhere on the filesystem. - **Builder mechanism**: The BuildKit-based builder VM receives the context as a tarball while reading the Dockerfile from your specified path, as documented in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) and [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md). ## Frequently Asked Questions ### What happens if I omit the `-f` flag? If you do not specify `-f` or `--file`, the builder searches the root of the build context for a file named `Dockerfile`. If that file does not exist, it automatically falls back to looking for `Containerfile`. This behavior is explicitly defined in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 170). ### Can the Dockerfile be located outside the build context? Yes. You can specify a Dockerfile path that is completely outside your build context directory using either relative paths (e.g., `../my-service/Dockerfile`) or absolute paths (e.g., `/opt/shared/Dockerfile`). However, note that `COPY` and `ADD` instructions within that Dockerfile still reference paths relative to the build context root you provide as the final argument. ### Does apple/container support Containerfile naming conventions? Yes. The tool supports both `Dockerfile` and `Containerfile` naming. When you don't specify a custom path with `-f`, the builder automatically looks for `Dockerfile` first, then `Containerfile` as a fallback. This allows compatibility with various container build standards without requiring renames. ### How does the builder VM access the Dockerfile when using a custom path? As implemented in `apple/container`, the builder launches a lightweight VM running BuildKit. The CLI tool reads the Dockerfile from your specified path (whether inside or outside the context) and passes it to the builder, while simultaneously packaging the build context directory as a tarball for transmission to the VM. This process is documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 69-71) and enables builds with completely separated Dockerfile and source contexts.