How can I create an ENV variable with literal newline characters in a Dockerfile?

Below is an explanation in context with the Docker documentation:

What's Happening

When using the Dockerfile's ENV instruction, the value you provide does not process backslash escape sequences the same way as, for example, the interpolation that happens with values in a Compose file’s .env file. In Dockerfiles the ENV instruction merely strips unneeded quotes and backslashes (unless those are intended to escape a space), meaning that a sequence like \n is not converted into a newline character—it remains as the literal characters \ and n.

Why This Happens

The Dockerfile processing of the ENV instruction is similar to simple command line parsing. Unlike in Compose files where double-quoted values support common shell escape sequences (such as \n converting to a newline), Dockerfiles do not interpret these escape sequences automatically. As a result, if you write:

DOCKERFILECopied
ENV FOO="line1\nline2"

Docker will set the environment variable FOO to the literal value:

line1\nline2

not

line1
line2

Workarounds

1. Set the Variable in the Compose File:
   Since you mentioned that putting the variable directly in the Compose file produces the correct output (because Compose’s interpolation handles escape sequences in double-quoted values), one valid workaround is to move this assignment there.

2. Use a Startup Script:
   Alternatively, you can initialize the environment variable in a startup script where you perform the conversion. For example, you can write your variable with a placeholder (or in literal form) and then in an entrypoint script replace those sequences with actual newline characters before starting your application.

   Example entrypoint snippet:

   BASHCopied
   #!/bin/sh
   # Replace the literal '\n' with an actual newline for FOO
   export FOO="$(echo "$FOO" | sed 's/\\n/\
   /g')"
   exec "$@"

In summary, the behavior you’re seeing is not a bug but rather how the Dockerfile ENV instruction is designed—it does not parse escape sequences for newline characters. Using the Compose file’s environment interpolation or a startup script to process the variable are the common solutions when you need actual newline characters in your environment variable.