Skip to content

buildkit/WorkdirRelativePath

Relative workdir can have unexpected results if the base image changes.

Property Value
Severity Warning
Category Best Practice
Default Enabled
Auto-fix Yes (suggestion --fix-unsafe; safe with --slow-checks)

Description

When specifying WORKDIR in a build stage, you can use an absolute path, like /build, or a relative path, like ./build. Using a relative path means that the working directory is relative to whatever the previous working directory was.

This rule warns if you use WORKDIR with a relative path without first specifying an absolute path in the same Dockerfile. The rationale is that using a relative working directory for a base image built externally is prone to breaking, since the working directory may change upstream without warning.

Examples

Bad (assumes WORKDIR in base image is /):

FROM nginx AS web
WORKDIR usr/share/nginx/html
COPY public .

Good:

FROM nginx AS web
WORKDIR /usr/share/nginx/html
COPY public .

Auto-fix

Replaces the relative WORKDIR with an absolute path.

  • Fast path (no registry access): resolves against / as a default (FixSuggestion, requires --fix-unsafe).
  • With --slow-checks: resolves against the base image's actual WORKDIR from the registry (FixSafe, applied with --fix). Chained relative WORKDIRs are resolved cumulatively.
# Before
FROM nginx AS web
WORKDIR usr/share/nginx/html

# After (with --fix-unsafe, fast path — assumes base WORKDIR is /)
FROM nginx AS web
WORKDIR /usr/share/nginx/html

# After (with --fix --slow-checks, base image has WORKDIR /etc/nginx)
FROM nginx AS web
WORKDIR /etc/nginx/usr/share/nginx/html

Supersedes

Reference