rubyguides

String#encode 

str.encode(encoding) -> string
Returns string· Updated May 18, 2026· String Methods
stringsencodingconversion

String#encode converts the encoding of a string to a specified target encoding. It returns a new string with the same characters but re-encoded, leaving the original string unchanged. This method is essential for handling multi-language text, fixing encoding issues, and ensuring strings are compatible with specific protocols or storage systems.

Use it when bytes arrive in one encoding but the rest of your Ruby program expects another. It is especially useful at system boundaries: files, CSV imports, HTTP payloads, mail headers, legacy databases, and command-line tools. For unsafe input, combine encode with replacement options so invalid bytes become predictable characters instead of runtime exceptions.

Syntax

string.encode(target_encoding)
string.encode(target_encoding, source_encoding)
string.encode(target_encoding, options)

Parameters

ParameterTypeDefaultDescription
target_encodingSymbolRequiredThe encoding to convert to (e.g., :UTF_8, :ISO-8859-1)
source_encodingSymbolnilThe current encoding of the string (Ruby attempts to detect if omitted)
optionsHash{}Conversion options like invalid: :replace, undef: :replace

Examples

Basic encoding conversion

string = "hello"
string.encoding
# => #<Encoding:UTF-8>

utf8_string = "hello"
utf8_string.encode(:ISO-8859-1)
# => "hello"
# Returns a new string in ISO-8859-1 encoding

Converting from ASCII-8BIT

binary_data = "hello".encode(Encoding::ASCII_8BIT)
# Convert bytes to UTF-8
binary_data.force_encoding("UTF-8")
# => "hello"

# Or use encode directly
binary_data.encode("UTF-8")
# => "hello"

Handling invalid characters

invalid_utf8 = "hello\xFFworld"
invalid_utf8.encode("UTF-8", invalid: :replace, undef: :replace)
# => "hello?world"

Common Patterns

Transcoding for file I/O

content = File.read("data.csv", encoding: "UTF-8")
# Convert to ASCII for legacy systems
ascii_content = content.encode("US-ASCII", undef: :replace, invalid: :replace)
File.write("data ascii.csv", ascii_content, encoding: "US-ASCII")

Normalizing Unicode

text = "café"
text.encode!("UTF-8")  # in-place conversion

# Use Unicode normalization forms
normalized = text.encode("UTF-8").normalize(:nfc)

Encoding detection and conversion

def convert_to_utf8(string)
  # First force UTF-8 encoding, then re-encode properly
  string.force_encoding("UTF-8").encode("UTF-8")
end

# Handle various input encodings
def sanitize_encoding(input)
  input.encode("UTF-8", invalid: :replace, undef: :replace)
end

Working with external APIs

# Convert string for HTTP requests
query = "search term"
encoded_query = query.encode("UTF-8")

# Convert for legacy database storage
legacy_string = "old data".encode("Windows-1252")

CSV encoding handling

require "csv"

# Read CSV with specific encoding
CSV.foreach("data.csv", encoding: "ISO-8859-1") do |row|
  # Convert each field to UTF-8
  utf8_row = row.map { |cell| cell.encode("UTF-8", invalid: :replace) }
  process(utf8_row)
end

Email and HTTP headers

# Encode subject for email (RFC 2047)
subject = "Subject: =?UTF-8?B?#{["café"].pack("m0")}?="
# => "Subject: Y2Fmw6k="

# Decode received subject
decoded = subject.force_encoding("UTF-8")

Errors

  • Encoding::UndefinedConversionError: Raised when the conversion is not defined between encodings. Handle with invalid: and undef: options.
  • Encoding::InvalidByteSequenceError: Raised when the string contains bytes invalid for the source encoding. Use invalid: :replace to handle.
  • ArgumentError: Raised when an invalid encoding name is provided.

See Also