How to encode and decode base64 in the Linux terminal

Despite being formalized some time ago — during the first wave of personal computers — base64 is widely used.

At its core, base64 is a method of encoding binary data (1's and 0's) into 6-bit characters. While its use is often invisible to the average user, it forms an important part of many systems, including email, image transmission, API requests, encryption, and more.

This guide will walk through the basics of base64 on Linux, including how it works, how to encode and decode it, and some real world examples relevant to VPS server use.

Need a VPS server? Sign up for BitLaunch and talk to our support for some free credit.

How to encode base64 in Linux

Every Linux system has the capability to encode and decode base64 via the in-built base64 command. Even better, the command has a simple syntax anybody can understand and remember.

There are two primary ways to encode base64 in Linux:

• We can print the string we want to encode directly in the command line using echo and use a pipe to redirect the output to the base64 command, where it is encoded.
• We can encode a pre-existing file by pointing the base64 command to it and then specifying what we want the encoded file to be named.

We'll refer to the first as encoding a string, and the latter encoding a file, though you can absolutely encode a string contained in a file using this method. Let's start by encoding a simple and timeless message: "Hello world!".

How to base64 encode a string in Linux

As mentioned previously, you can make use of the echo command to base64 encode a string in-line in Linux. In its most basic form, the syntax looks like this:

echo -n "base64string" | base64

The echo -n command displays our string in the terminal, with the -n option doing so while omitting new lines. The pipe character (|) tells the system that we want to pass the output of echo to another command rather than displaying it, in this case to the base64 command for decoding.

Let's make this a little clearer using our example. In your Linux command line, type:

echo -n "Hello world!" | base64

You'll immediately see the "Hello world!" string output in base64:

SGVsbG8gd29ybGQh

How to base64 encode a file in Linux

The syntax for base64 encoding a file in Linux is even simpler:

base64 yourfilename > outputfilename

Let's start by creating a text file that we can use as the input file, containing the string "Hello world!":

echo -e "Hello world!" >> helloworld.txt

Now let's encode it with base64. We'll name the encoded file helloworld_encoded.

base64 helloworld.txt > helloworld_encoded.txt

If you run ls, you'll see that our output file has been created.

You can view its contents with cat helloworld_encoded.txt.

Real-world example: Sending small binary files via text-only channels

There are certain scenarios where you may to send a file in base64. For example, you're using email, rest APIs, or certain database fields which strip or corrupt binary data. You might also want to embed a file in a script in base64 format if you only have access to a restricted VPS command-line interface with no SCP or SFTP.

Want a private VPS server with no restrictions? Get started with BitLaunch in seconds.

We'll choose a simple example: transferring a logo image to our VPS server without using FTP. First, we encode it using:

base64 logo.png > logo.png.b64

Now we can open the file and copy the base64 to transfer it to our server using:

echo "pastebase64codehere" | base64 -d > logo.png

More commonly, encoding an image like this could be used to in-line assets in HTML, CSS, or email templates, for example:

<img src="data:image/png;base64,iVBORw0K..." alt="logo">

How to decode base64 in Linux

Base64 decoding in the Linux CLI is almost identical to encoding. The only difference is that this time we'll be using the base64 -d command instead of plain base64. Let's start with the simple "Hello world!" text we encoded earlier, before moving onto some more useful real-life examples.

You can decode base64 that you paste directly into the CLI with the following syntax:

echo -n "base64string" | base64 -d

echo -n here is just a way to print our text, which is passed on to the base64 command through the use of pipes (|) . -d is the important option here, as it activates base64's decode option, rather than the default encoding.

So, in the case of our example:

echo -n "SGVsbG8gd29ybGQh" | base64 -d

Output:
Hello world!

More commonly, perhaps, you may want to decode an existing file that's base64 encoded. The syntax here is even easier:

base64 -d helloworld_encoded.txt > helloworld_decoded.txt

How to base64 decode each line in a file

Some files contain several separate lines of base64 that you need to decode separately. Here's an example which we have created in a file called "hello.txt":

SGVsbG8=
ZnJvbQ==
Qml0TGF1bmNo

Some creative use of while loops allows us to use bash to base64 decode our file and print it in the terminal:

while read -r line; do
  echo "$line" | base64 --decode
  echo
done < hello.txt

Output:
Hello
from
BitLaunch

while read -r line; do reads our file line-by-line and stores the text of each in a variable, $line. The text from line is then piped to base64 for decoding and finally printed with a blank line between each for readability.

Real-world example: Decoding an API key

It can occasionally be useful to decode an API token to troubleshoot misconfiguration and verify that the credentials were correctly encoded before being sent to an API.

Let's use this real-life Google Cloud key as an example:

AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe

If we convert the base64 to a string using echo -n "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" | base64 -d, we get an invalid input error. That's because the key is using URL-safe base64, which replaces plusses with minuses and slashes with underscores.

One way to resolve this is by piping in the translate (tr) command after our echo and adding = to the end until the string is divisble by 4:

echo 'AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe=' \
| tr '_-' '/+' | base64 --decode

Output:
��K �␦e�k�l]���l;!"��yژ��

Note that our output here looks like gibberish because it is. This particular API key consists of raw binary bytes, and our terminal is trying and failing to output it as UTF-8 text. If you wanted to view the decoded binary as something human-readable, you could hexdump it:

echo -n "AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe" \
| tr '_-' '/+' | base64 --decode | hexdump -C

Output:
00000000  8f 92 4b 20 9f b6 96 65  ab 6b 8e 6c 5d 9b d2 9b  |..K ...e.k.l]...|
00000010  6c 3b 21 22 d2 b0 79 d8  a7 9b 88 00              |l;!"..y.....|

Real-world example: Decoding a JWT payload

JSON Web Tokens (JWTs) often include Base64-encoded headers and payloads. Let's use this example:

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0.KMUFsIDTnFmyG3nMiGM6H9FNFUROf3wh7SmqJp-QV30

The payload is the string between the two .'s. Using echo to decode it, we get the JSON output:

echo -n "eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWUsImlhdCI6MTUxNjIzOTAyMn0" | base64 -d

Output:
{
"sub":"1234567890",
"name":"John Doe",
"admin":true,
"iat":1516239022
}

Closing words and further reading

That should be enough to get you started encoding and decoding base64 in the Linux VPS command line. Just remember that knowing when to use a tool is just as important as knowing how to use it. Base64 encoding can have some downsides, including:

• Increased memory consumption. In particular, for image sprites in websites and web apps.
• Roughly 33-37% larger file sizes compared to the original binary representation. Sometimes, this will be worth it to reduce things like the number of HTTP requests. Other times, not.
• It doesn't increase security. Some people mistake encoding for encryption. As we've seen today, anybody can decode base64 instantly. You should use AES or GPG encryption to protect sensitive data from prying eyes.
• It's not human-readable. Base64 makes logging and debugging more hassle. You might not get a perfectly formatted result after decoding without some extra effort.

For further reading on the downsides of base64, we recommend these writeups by CSSWizardry and Daniel Lemire, which provide some real-world tests of its performance impact.

Found this guide helpful? Say thanks by checking out our high-speed VPS servers.  Our one-click apps let you launch your website, VPN, or development environment in minutes.