How to Base64 Encode Any File

← Back to Blog

How to Base64 Encode Any File

· 5 min read

Use Cases for File Base64 Encoding

Base64 encoding files is very useful in scenarios such as: transmitting binary files through REST APIs (JSON format); storing file contents in JSON or YAML configuration files; storing certificates and keys in Kubernetes Secret resources; packaging multiple files into a single text format for transmission; and sending files through APIs that don't support multipart form uploads.

Base64 encoding allows any file (whether PDF, image, audio, video, or executable) to be treated as a plain text string, greatly simplifying the complexity of cross-system data exchange.

Encoding Files with Command Line Tools

# Linux / macOS
# 编码文件并输出到屏幕 / Encode file and output to screen
base64 document.pdf

# 编码文件并保存到新文件 / Encode file and save to new file
base64 document.pdf > document.pdf.b64

# 不含换行符输出（适合 API 使用）/ Output without line breaks (for API use)
base64 -w 0 document.pdf > document.pdf.b64

# 解码 / Decode
base64 -d document.pdf.b64 > restored.pdf

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("document.pdf")) |
  Out-File -Encoding ascii document.pdf.b64

# 解码 / Decode
$bytes = [Convert]::FromBase64String((Get-Content document.pdf.b64))
[IO.File]::WriteAllBytes("restored.pdf", $bytes)

Encoding Any File in Python

import base64
import json
from pathlib import Path

def encode_file_to_base64(file_path):
    """读取文件并返回 Base64 字符串"""
    with open(file_path, 'rb') as f:
        return base64.b64encode(f.read()).decode('ascii')

def decode_base64_to_file(base64_str, output_path):
    """将 Base64 字符串解码并写入文件"""
    data = base64.b64decode(base64_str)
    with open(output_path, 'wb') as f:
        f.write(data)
    return len(data)

# 将文件嵌入 JSON / Embed file in JSON
def file_to_json_payload(file_path):
    path = Path(file_path)
    return {
        "filename": path.name,
        "size": path.stat().st_size,
        "content": encode_file_to_base64(file_path)
    }

payload = file_to_json_payload("report.pdf")
json_str = json.dumps(payload)
print(f"JSON payload size: {len(json_str)} chars")

Encoding Files in Node.js

const fs = require('fs');
const path = require('path');

// 同步方式 / Synchronous
function encodeFileSync(filePath) {
  return fs.readFileSync(filePath).toString('base64');
}

// 异步方式（推荐用于生产）/ Async (recommended for production)
async function encodeFileAsync(filePath) {
  const data = await fs.promises.readFile(filePath);
  return data.toString('base64');
}

// 流式处理大型文件 / Stream large files
const { createReadStream } = require('fs');
const { Transform } = require('stream');

function encodeFileStream(inputPath, outputPath) {
  const readStream = createReadStream(inputPath);
  const writeStream = fs.createWriteStream(outputPath);
  const base64Transform = new Transform({
    transform(chunk, encoding, callback) {
      callback(null, chunk.toString('base64'));
    }
  });
  readStream.pipe(base64Transform).pipe(writeStream);
}

File Encoding in Kubernetes Secrets

Kubernetes Secret resources use Base64 to store sensitive data (like certificates, keys, and config files). In a Secret's YAML file, every value under the data field must be Base64-encoded. Note: the kubectl create secret command automatically handles Base64 encoding, but when manually writing YAML you need to encode yourself.

# 生成 Kubernetes Secret 的 YAML
# Generate Kubernetes Secret YAML
CA_CERT=$(base64 -w 0 ca.crt)
TLS_KEY=$(base64 -w 0 server.key)

cat  secret.yaml
apiVersion: v1
kind: Secret
metadata:
  name: tls-secret
type: kubernetes.io/tls
data:
  tls.crt: ${CA_CERT}
  tls.key: ${TLS_KEY}
EOF

kubectl apply -f secret.yaml

Considerations for Large Files

When Base64-encoding large files, pay special attention to memory usage. A 100MB file becomes about 133MB after Base64 encoding, which can be a problem in memory-constrained environments. For files larger than several tens of MB, streaming is recommended rather than reading the entire file into memory at once.

Another consideration is transmission efficiency. Base64's 33% size overhead is acceptable for small files, but for large media files, using multipart/form-data format to directly upload binary data is recommended — no size overhead, and most web frameworks and cloud storage services support it natively.

Verifying the Integrity of Encoded Results

Before using a file's Base64-encoded result in a production system, it's recommended to verify its integrity: decode the Base64 string and compare with the original file's hash (MD5 or SHA-256) to ensure data wasn't corrupted during encoding/decoding.

import base64
import hashlib

def verify_base64_file(original_path, base64_str):
    """验证 Base64 字符串是否与原文件一致"""
    # 计算原始文件的 SHA-256
    with open(original_path, 'rb') as f:
        original_hash = hashlib.sha256(f.read()).hexdigest()

    # 解码 Base64 并计算哈希
    decoded = base64.b64decode(base64_str)
    decoded_hash = hashlib.sha256(decoded).hexdigest()

    if original_hash == decoded_hash:
        print("Integrity verified: hashes match")
        return True
    else:
        print(f"MISMATCH! Original: {original_hash}, Decoded: {decoded_hash}")
        return False

Try the online tool now — no installation, completely free.

Open Tool →