Encode and Decode Files Safely with GNU base64

Turning a file into Base64 text with base64 is the easy part; keeping the original safe while you do it is where people trip up. You will encode a file or stream, decode it back to its original bytes, and verify the round trip. Allow about ten minutes. You need a shell, a readable input file, and write access to the destination directory.

• Version used here: GNU coreutils 9.4, installed as package version 9.4-3ubuntu6.3.
• It is encoding, not encryption. Anyone who receives the encoded text can decode it, so do not use base64 to protect passwords, tokens or private files.

1. Check the installed command

$ command -v base64
/usr/bin/base64
$ base64 --version | head -n 1
base64 (GNU coreutils) 9.4

These are ordinary, read-only commands and need no elevated privileges. The command accepts one optional file name; with no file, or with -, it reads standard input, and it writes the encoded or decoded bytes to standard output, so shell redirection decides where the result lands.

2. Encode a file as Base64 text

$ base64 /path/to/input.bin > /path/to/input.bin.b64

This does not change the input; replace the placeholder paths with files you control.

• Wrapping by default: GNU base64 wraps encoded output after 76 characters. It is still Base64 data, and newlines are permitted during decoding.
• Inspect without opening in an editor:

  $ wc -c /path/to/input.bin /path/to/input.bin.b64
  $ head -n 2 /path/to/input.bin.b64

• For a single-line value, disable wrapping with --wrap=0:

  $ base64 --wrap=0 /path/to/input.bin > /path/to/input.bin.one-line.b64
  $ awk 'length > 0 { print length; exit }' /path/to/input.bin.one-line.b64
  # the encoded line length is printed here

  The line length depends on the input size; a short file does not always produce a fixed-length value.

3. Decode the text back to bytes

$ base64 --decode /path/to/input.bin.b64 > /path/to/round-trip.bin

Use --decode, or its short form -d, and redirect the result to a new path. Then verify the decoded file is byte-for-byte identical to the original:

$ cmp --silent /path/to/input.bin /path/to/round-trip.bin
$ printf 'comparison status: %s\n' "$?"
comparison status: 0

4. Test a stream without creating an input file

$ printf 'hello Linux\n' | base64 | base64 --decode
hello Linux

Standard input and output make base64 useful in a pipeline; this example encodes a known line and immediately decodes it. The final newline is part of the input supplied by printf, so it is also present in the decoded result. For reproducible test data, prefer printf to an unquoted echo, whose handling of backslashes and options varies between shells.

$ encoded=$(printf 'hello Linux\n' | base64 --wrap=0)
$ test "$encoded" = 'aGVsbG8gTGludXgK'
$ printf 'known-value check: %s\n' "$?"
known-value check: 0

5. Handle line wrapping deliberately

$ printf '1234567890\n' | base64 --wrap=4
MTIz
NDU2
Nzg5
MAo=

Use --wrap=COLS when another program expects a particular encoded line width. This option affects encoding output only. During decoding, ordinary newlines are accepted as part of the encoded stream, so a line break inserted for display is not the same thing as arbitrary junk in the input.

6. Deal with invalid or contaminated input

$ printf 'aGVs!bG8=\n' | base64 --decode --ignore-garbage
hello

Decoding normally accepts Base64 characters and newlines. With --ignore-garbage, GNU base64 attempts to ignore other non-alphabet characters.

7. Avoid overwriting useful output

Shell redirection with > truncates an existing destination before base64 starts. For output that matters, write a temporary file in the same directory, check it, then replace the destination:

$ base64 /path/to/input.bin > /path/to/input.bin.b64.new && \
  cmp --silent /path/to/input.bin.b64.new /path/to/input.bin.b64 && \
  mv /path/to/input.bin.b64.new /path/to/input.bin.b64

Only use that exact pattern when the old Base64 file is expected to be identical. For a new conversion, check the temporary file first, then move it explicitly:

$ base64 /path/to/input.bin > /path/to/output.b64.new && \
  test -s /path/to/output.b64.new && \
  mv /path/to/output.b64.new /path/to/output.b64

If the command fails, remove the incomplete .new file after checking its path; the original destination remains untouched. mv changes directory state, but it needs no elevated privileges when you own the directory.