How to Source Scripts with Environment Variables in Docker Build: A Complete Guide (2026)

In Docker, handling environment variables can be a bit tricky, especially when trying to source scripts during the build process. This guide will teach you how to effectively source a script with environment variables in a Docker build, ensuring your variables are available at runtime. We'll explore why this is important, walk through a step-by-step solution, and troubleshoot common issues.

Key Takeaways

• Understanding the Docker build process and environment variable scope.
• Techniques to source scripts with environment variables during Docker build.
• Common pitfalls and how to avoid them.
• Maintaining script portability and compatibility.

Introduction

Docker is a powerful tool for creating isolated environments, but managing environment variables can be a challenge. When building Docker images, it's common to need environment variables set by scripts. However, due to the way Docker layers work, simply using RUN source /env.sh doesn't persist these variables in the final running container.

In this tutorial, we'll explore the correct approach to sourcing environment variables from a script during a Docker build. This knowledge is crucial for ensuring your Docker containers behave as expected, especially in complex projects where multiple services interact.

Prerequisites

• Basic understanding of Docker and Dockerfiles.
• Docker installed on your machine (Docker 24.0 or later recommended).
• Familiarity with shell scripting basics.

Step 1: Understand Why Environment Variables Disappear

First, it's important to understand why sourcing a script in a Dockerfile doesn't persist variables. Docker builds images in layers, and each RUN command creates a new layer. Environment variables set in one layer are not accessible in subsequent layers.

This is because each RUN command starts a new shell session, and variables set in a previous session are not carried over. Therefore, sourcing a script with RUN source /env.sh alone will not work as expected.

Step 2: Use the ENV Instruction

To persist environment variables, you can use the ENV instruction in your Dockerfile. This instruction sets environment variables that are available during build and runtime. However, it doesn't support complex script logic directly.

FROM alpine:3.9.3

# Set environment variable directly
ENV TEST_VAR=test123

CMD env

While this works for simple variables, it doesn't help if your script performs calculations or conditional logic.

Step 3: Use a docker-entrypoint.sh Script

For more complex scripts, a common pattern is to use an entrypoint script. This script is executed when the container starts, allowing for dynamic environment setup:

#!/bin/sh

# Source your script
. /env.sh

# Execute the command passed to the container
exec "$@"

Modify your Dockerfile to copy and use this entrypoint script:

FROM alpine:3.9.3

COPY ./env.sh /env.sh
COPY ./docker-entrypoint.sh /docker-entrypoint.sh
RUN chmod +x /docker-entrypoint.sh
ENTRYPOINT ["/docker-entrypoint.sh"]
CMD ["env"]

This approach ensures that environment variables are set when the container starts, preserving any logic in env.sh.

Step 4: Verify the Environment Variables

To verify that your environment variables are correctly sourced, build and run the Docker image:

docker build -t sandbox .
docker run --rm sandbox

You should see the output that includes your environment variables:

HOSTNAME=
TEST_VAR=test123
SHLVL=1
HOME=/root
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
PWD=/

Common Errors/Troubleshooting

• Script Not Found: Ensure the script path is correct and the file is copied into the image.
• Permission Denied: Make sure the entrypoint script has executable permissions (use chmod +x).
• Variables Still Missing: Double-check the script logic and ensure it correctly exports variables.

Conclusion

Sourcing scripts with environment variables in Docker builds requires understanding the build process and leveraging entrypoint scripts. By following this guide, you can ensure that your environment variables are set correctly, allowing your Docker containers to run as expected.

Frequently Asked Questions

Can I use complex scripts in Dockerfile?

Yes, but it's best to use an entrypoint script to handle complex logic and set environment variables dynamically.

Why are my variables missing after building?

Environment variables set during the build are not preserved across layers; use an entrypoint script to ensure they are set at runtime.

What if my script needs to run before every command?

Use a wrapper script as the entrypoint and call your command within it to set variables before execution.

Frequently Asked Questions

Can I use complex scripts in Dockerfile?

Yes, but it's best to use an entrypoint script to handle complex logic and set environment variables dynamically.

Why are my variables missing after building?

Environment variables set during the build are not preserved across layers; use an entrypoint script to ensure they are set at runtime.

What if my script needs to run before every command?

Use a wrapper script as the entrypoint and call your command within it to set variables before execution.