Instrucción WORKDIR Dockerfile

En un Dockerfile, WORKDIR establece el directorio de trabajo dentro de la imagen para las instrucciones que vienen después. Afecta a RUN, CMD, ENTRYPOINT, COPY y ADD; también define el directorio inicial del contenedor, salvo que se cambie al ejecutarlo.

La ruta puede ser absoluta o relativa. Las relativas se calculan a partir del WORKDIR anterior y, si no declaras uno al principio, la imagen base podría aportar un valor propio. Una ruta absoluta como /app evita depender de esa configuración heredada.

👉 Y recuerda, si quieres aprender más de Linux, visita el curso de Linux gratis.

🐳 Si quieres aprender más de Docker, visita el curso de Docker gratis.

Qué cambia al declarar WORKDIR

Docker conserva el directorio elegido en la configuración de la imagen. Si la ruta no existe, la crea dentro de la imagen; no crea una carpeta en tu equipo anfitrión. Cada nueva instrucción WORKDIR cambia la ubicación de trabajo para las instrucciones siguientes.

El directorio actual afecta a los comandos de construcción y al proceso que inicia el contenedor. Por ejemplo, RUN pwd se ejecuta desde ese directorio, y una aplicación lanzada por CMD o ENTRYPOINT también parte de él. En cambio, un RUN cd /app no establece el directorio para las instrucciones posteriores: usa WORKDIR para dejarlo definido.

Cómo se resuelven las rutas absolutas y relativas

Una ruta que empieza por / se interpreta desde la raíz del sistema de archivos de la imagen. Una ruta relativa se añade al directorio de trabajo previo, que puede proceder de otra instrucción WORKDIR o de la imagen indicada en FROM.

Por eso conviene declarar un WORKDIR absoluto al comienzo de cada etapa. Evitas que un cambio de imagen base desplace rutas relativas y cambie dónde se copian archivos o desde dónde arranca la aplicación.

Relación entre WORKDIR y COPY

En COPY origen destino, el origen local se busca dentro del contexto de construcción; no se busca desde WORKDIR. Si el destino es relativo, se coloca dentro del directorio de trabajo actual. En el ejemplo, los archivos del contexto se copian a /app porque el destino es . después de WORKDIR /app.

Las instrucciones RUN, CMD y ENTRYPOINT también usan ese directorio como ubicación de ejecución. Las rutas absolutas de esas instrucciones siguen apuntando a su ubicación explícita, aunque cambie WORKDIR.

Ejemplo práctico con WORKDIR en un Dockerfile

Este Dockerfile fija una ruta estable antes de copiar dependencias y ejecutar comandos. WORKDIR crea /app dentro de la imagen si todavía no existe.

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY . .
CMD ["node", "server.js"]

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --omit=dev
COPY . .
CMD ["node", "server.js"]

La primera instrucción COPY toma package.json y el archivo de bloqueo desde el contexto, pero los guarda en /app. RUN npm install se ejecuta desde esa carpeta y CMD inicia Node con el mismo directorio de trabajo.

Puedes comprobar el directorio configurado en la imagen con docker image inspect web-demo:1.0 --format '{{.Config.WorkingDir}}'. Al iniciar un contenedor, docker run --workdir /tmp … permite sustituir ese valor para esa ejecución.

Errores frecuentes y cómo evitarlos

• Usar una ruta relativa sin revisar el directorio heredado de la imagen base; define primero una ruta absoluta.
• Confundir el origen y el destino de COPY: el origen pertenece al contexto y el destino relativo se resuelve desde WORKDIR.
• Usar RUN cd carpeta esperando que afecte a otra instrucción; el cambio solo dura dentro de ese comando.
• Suponer que WORKDIR crea una carpeta en el host; solo crea o selecciona una ruta dentro de la imagen.
• Cambiar el directorio al arrancar con --workdir sin comprobar si la aplicación encuentra sus archivos relativos.

Lecciones relacionadas del curso Docker

• Instrucción COPY: distingue el contexto de construcción del destino dentro de la imagen.
• Flujo básico Dockerfile, imagen y contenedor: relaciona el Dockerfile con la imagen construida y el contenedor en ejecución.
• Qué es .dockerignore: controla qué archivos entran en el contexto de construcción.

Documentación oficial

• Docker Docs: instrucción WORKDIR.
• Docker Docs: instrucción COPY.

Declara una ruta absoluta y estable para que las instrucciones posteriores y la aplicación trabajen desde el lugar esperado. Revisa por separado la carpeta de origen del contexto, el destino de COPY y cualquier valor que se pueda sobrescribir al ejecutar el contenedor.