encoding/hex

Hexadecimal encode and decode, including odd-length ErrLength and InvalidByteError, checked on Go 1.24.0.

The encoding/hex package encodes and decodes hexadecimal bytes. Import it as "encoding/hex". Examples were checked on Go 1.24.0.

DecodeString requires an even-length string of hexadecimal digits. Odd length returns the package sentinel ErrLength. An illegal digit returns an InvalidByteError whose value is that byte. This page is not a general strings or strconv reference.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
hex.EncodeToString, hex.DecodeStringEncode bytes as lowercase hex, and decode an even-length hex string back to bytes.
hex.ErrLength, hex.InvalidByteErrorDetect an odd-length hex string or an illegal hex digit without depending on the error string.

EncodeToString and DecodeString

EncodeToString writes two lowercase hex digits per input byte. DecodeString inverts that, and official documentation states that it expects only hexadecimal characters and even length. On success the error is nil. If the input is malformed, DecodeString returns the bytes decoded before the error.

hex.EncodeToString, hex.DecodeString

func EncodeToString(src []byte) string
func DecodeString(s string) ([]byte, error)
func EncodedLen(n int) int
func DecodedLen(x int) int

Encode bytes as lowercase hex, and decode an even-length hex string back to bytes.

ParameterDescription
src / sEncodeToString takes the bytes to encode. DecodeString takes a string of 0-9a-fA-F digits with even length.

Returns: EncodeToString returns a string twice as long as src. DecodeString returns the decoded bytes and a nil error when s is well formed.

  • AppendEncode and AppendDecode, added in Go 1.22, append to a destination slice. They are not shown here.
go
package main

import (
	"encoding/hex"
	"fmt"
)

func main() {
	fmt.Println(hex.EncodeToString([]byte{0x00, 0xff, 0x10}))
	out, err := hex.DecodeString("00ff10")
	fmt.Printf("%x %v\n", out, err)
}

Expected output

00ff10
00ff10 <nil>

Related: crypto/sha256

Official documentation →

Odd length and invalid bytes

hex.ErrLength is the error for an odd-length string such as "abc". Official documentation notes that the stream Decoder returns io.ErrUnexpectedEOF instead of ErrLength; this page uses DecodeString only.

InvalidByteError is a byte type whose value is the first illegal character. Decoding "zz" yields InvalidByteError with value 122, which is the byte z. Compare these errors with errors.Is and errors.As rather than with operating-system or localized text.

hex.ErrLength, hex.InvalidByteError

var ErrLength = errors.New("encoding/hex: odd length hex string")
type InvalidByteError byte

Detect an odd-length hex string or an illegal hex digit without depending on the error string.

ParameterDescription
sDecodeString input. Length must be even, and every character must be a hex digit.

Returns: Partial decoded bytes and a non-nil error when s is malformed.

Errors

  • ErrLength — Decode or DecodeString was given an odd-length string. Compare with errors.Is.
  • InvalidByteError — A character is not a hex digit. The integer value is that byte, for example 122 for z.
go
package main

import (
	"encoding/hex"
	"errors"
	"fmt"
)

func main() {
	_, err := hex.DecodeString("abc")
	fmt.Println(errors.Is(err, hex.ErrLength))
	var ib hex.InvalidByteError
	_, err = hex.DecodeString("zz")
	fmt.Println(errors.As(err, &ib), byte(ib))
}

Expected output

true
true 122

Official documentation →