🐳 DockerFile RUN Instruction – Complete Guide with Best Practices & Examples

🧲 Introduction – Why Learn the RUN Instruction in Docker?

The RUN command is one of the most fundamental and powerful tools in any Dockerfile. It allows you to execute shell commands during the build process of your Docker image. From installing dependencies to setting permissions or compiling source code—RUN is how you customize and configure your image before it runs.

🎯 In this guide, you’ll learn:

• What the RUN command does and how it works
• The syntax differences (Shell vs Exec)
• Optimization strategies to reduce image size
• Common mistakes and real-world usage examples

---

🧠 What is the RUN Command in a DockerFile?

The RUN instruction executes commands at build time, creating a new layer on top of the current image. This layer is then committed and added to the final image. It’s ideal for installing software, downloading files, modifying system configuration, and more.

🔹 Syntax:

RUN <command>

🐚 Shell Form

RUN apt-get update && apt-get install -y nginx

✅ Uses /bin/sh -c by default. Supports:

• Shell features (&&, ||, >, variable expansion)

⚙️ Exec Form (JSON Array Format)

RUN ["apt-get", "install", "-y", "nginx"]

✅ Does not use a shell. Executes commands directly. Useful for:

• Precise command execution
• Avoiding shell parsing issues

---

🔍 How RUN Works in a DockerFile

• ✅ Creates a new image layer after each execution
• ⚠️ Executed only during the image build phase, not when the container starts
• 📦 Impacts final image size—unoptimized usage can result in bloat

📌 Pro Tip: Use && to combine related commands in a single RUN to minimize the number of layers.

---

📦 Real-World Example – Installing Dependencies

FROM ubuntu:20.04

RUN apt-get update && \
    apt-get install -y curl git vim && \
    rm -rf /var/lib/apt/lists/*

✅ This example:

• Installs multiple packages
• Combines commands using && to reduce layers
• Cleans up cache to reduce image size

---

🧰 DockerFile RUN Command – Function Table

🛠️ Function	📝 Description	📌 Example
Install packages	Use OS package managers	RUN apt-get install -y curl
Clean up files	Reduce image bloat	RUN apt-get clean && rm -rf /var/lib/apt/lists/*
Create/modify files	Add or edit files/directories	RUN mkdir /data && touch /data/info.txt
Edit configs	Customize settings	RUN echo "alias ll='ls -la'" >> ~/.bashrc
Execute scripts	Run custom shell scripts	RUN ./install.sh
Change permissions	Adjust file access rights	RUN chmod +x /app/start.sh
Download files	Pull from internet	RUN curl -O https://example.com/file.tar.gz
Extract archives	Unpack zipped content	RUN tar -xzf file.tar.gz -C /opt
Compile code	Build from source	RUN gcc -o app main.c
Chain commands	Reduce layers	RUN apt update && apt install -y vim
Use ENV variables	Inject environment configs	RUN echo "ENV=$APP_ENV"
Add security certs	Enhance trust	RUN update-ca-certificates
Run tests/builds	Verify during build	RUN npm install && npm test
Install runtimes	Add interpreters	RUN apt install -y nodejs
Create users/groups	Add OS users	RUN useradd -ms /bin/bash devuser

---

✅ Best Practices for RUN in Dockerfile

🔧 Combine Commands Wisely

RUN apt-get update && apt-get install -y \
    python3 python3-pip && \
    rm -rf /var/lib/apt/lists/*

🔄 Chaining commands reduces image layers and speeds up builds.

🧹 Always Clean Up
Remove temporary files or cached data to reduce image size:

RUN apt-get clean && rm -rf /var/lib/apt/lists/*

🛡️ Use Exec Form for Precision

RUN ["bash", "-c", "echo Hello && echo World"]

Exec form avoids shell-related parsing issues.

---

❌ Common Mistakes to Avoid

❗ Mistake	🧹 Better Approach
Multiple RUN commands	Combine with && to reduce layers
Forgetting cleanup	Always clean apt/yum cache to reduce size
Relying only on Shell form	Use Exec form when precision is needed

---

📘 Real-World Dockerfile Snippet

FROM node:18

WORKDIR /app

COPY . .

RUN npm install && npm run build

CMD ["node", "server.js"]

🔍 RUN npm install && npm run build installs dependencies and builds the app during the build stage, ensuring your app is ready when the container starts.

---

📝 Summary – Recap & Takeaways

The RUN instruction is your tool for customizing Docker images during the build process. From installing software to configuring settings, it’s essential to use it wisely to keep your image optimized.

🔍 Key Takeaways:

• Executes at build time, not runtime
• Creates new layers, which can bloat the image if misused
• Supports both Shell and Exec syntax forms
• Combine commands and clean up to keep your image lean
• Use ENV, scripts, and chaining for full control

⚙️ Real-World Impact:
Efficient use of RUN reduces Docker image sizes, speeds up deployments, and ensures consistency across environments.

---

❓FAQs – DockerFile RUN Command

❓ Q1. Does RUN execute when the container starts?
❌ No. RUN executes only during image build. Use CMD or ENTRYPOINT for runtime actions.

---

❓ Q2. Can I use environment variables in RUN?
✅ Yes, declare with ENV:

ENV PORT=3000
RUN echo "Server runs on port $PORT"

---

❓ Q3. Can I execute a shell script using RUN?
✅ Absolutely. Just COPY the script first:

COPY setup.sh .
RUN chmod +x setup.sh && ./setup.sh

---

❓ Q4. What’s the difference between RUN and CMD?

Instruction	When It Runs	Purpose
RUN	During image build	Setup image
CMD	At container startup	Default container behavior

---

❓ Q5. How do I reduce layers created by RUN?
✅ Combine commands:

RUN apt-get update && apt-get install -y nginx && rm -rf /var/lib/apt/lists/*

---

Share Now :