Convert String to Integer in Go: Idiomatic Parsing with strconv.Atoi

By the end of this page, you will understand how to convert a string to an integer in Go using the standard library, especially strconv.Atoi. You will also learn how to handle invalid input, how parsing works step by step, and when to use related functions such as strconv.ParseInt.

In Go, values do not automatically change from one type to another. If you have a string like "42" and want an integer, you must parse the string.

The idiomatic way to convert a decimal string to an int is:

strconv.Atoi(s)

This function belongs to Go's strconv package. It reads a string and tries to interpret it as a base-10 integer.

Why this matters:

• Command-line arguments are often strings.
• Data from files, APIs, and environment variables usually arrives as text.
• Programs often need numeric values for calculations, limits, counts, or indexes.

In Go, parsing returns two values:

• the parsed integer
• an error

That error is important. If the input is not a valid integer, Go expects you to handle the failure explicitly.

Example:

n, err := strconv.Atoi("42")

• n becomes 42
• err becomes nil

If the string were "abc", parsing would fail and err would contain information about the problem.

This explicit error handling is a core part of writing reliable Go code.

Think of parsing like reading a number written on a note.

• A string is the note: it contains characters.
• An int is the actual numeric value your program can calculate with.
• strconv.Atoi is the reader that checks whether the note really contains a valid whole number.

If the note says "123", the reader gives you the number 123. If the note says "hello", the reader cannot turn that into a number, so it reports an error.

So the idea is:

• strings are text
• ints are numeric values
• parsing is the process of turning valid text into a number

Basic syntax

value, err := strconv.Atoi(s)

• s must be a string
• value is the parsed int
• err is nil if parsing succeeds

You need to import the package first:

import "strconv"

Example with flag.Arg

package main

import (
	"flag"
	"fmt"
	"strconv"
)

func main() {
	flag.Parse()

	arg := flag.Arg(0)
	if arg == "" {
		fmt.Println("Please provide a number.")
		return
	}

	n, err := strconv.Atoi(arg)
	if err != nil {
		fmt.Println("Invalid number:", err)
		return
	}

	fmt.Println("Parsed integer:", n)
}

Consider this code:

package main

import (
	"fmt"
	"strconv"
)

func main() {
	s := "42"
	n, err := strconv.Atoi(s)
	if err != nil {
		fmt.Println("parse failed")
		return
	}
	fmt.Println(n)
}

Step-by-step

1. s := "42"

   • A string variable named s is created.
   • Its value is the text "42".

2. n, err := strconv.Atoi(s)

   • Go calls strconv.Atoi with s.
   • The function reads the characters in "42".
   • Since "42" is a valid integer, it returns:
     • n = 42
     • err = nil

String-to-integer conversion is very common in Go programs.

Command-line tools

Arguments from flag.Arg() are strings. You often parse them into numbers for:

• port numbers
• retry counts
• time limits
• item IDs

Environment variables

Configuration values often come from environment variables as strings:

portStr := os.Getenv("APP_PORT")
port, err := strconv.Atoi(portStr)

Reading files

A file may contain numeric text such as:

• user ages
• scores
• quantities
• record IDs

API and form input

Even when a value represents a number, it may arrive as a string in:

• JSON fields stored as strings
• URL query parameters
• form submissions

Data processing

CSV and text-based formats often store numbers as text. Parsing is required before calculations, sorting, or validation.

In real Go codebases, developers usually combine strconv.Atoi with validation and clear error handling.

Common pattern: parse and validate

count, err := strconv.Atoi(flag.Arg(0))
if err != nil {
	return fmt.Errorf("count must be an integer: %w", err)
}
if count < 0 {
	return fmt.Errorf("count must be non-negative")
}

This pattern is common because parsing alone does not guarantee the value is meaningful.

Guard clause style

Go code often exits early when input is invalid:

arg := flag.Arg(0)
if arg == "" {
	return
}

n, err := strconv.Atoi(arg)
if err != nil {
	return
}

This keeps the code simple and readable.

Wrapping errors

In larger projects, developers often wrap parsing errors with context:

n, err := strconv.Atoi(input)
if err != nil {
	return fmt.Errorf("invalid user id %q: %w", input, err)
}

This makes logs and debugging much more useful.

1. Forgetting to import strconv

Broken code:

n, err := Atoi("123")

Why it fails:

• Atoi is not in the current package.
• You must import strconv and call strconv.Atoi.

Correct version:

import "strconv"

n, err := strconv.Atoi("123")

2. Ignoring the error

Broken code:

n, _ := strconv.Atoi("abc")
fmt.Println(n)

Why it is a problem:

• Invalid input returns an error.
• If you ignore it, n may be 0, which can hide bugs.

Better version:

n, err := strconv.Atoi("abc")
if err != nil {
	fmt.Println("invalid integer")
	
}

strconv.Atoi vs strconv.ParseInt

Example

n, err := strconv.Atoi("42")

vs.

n64, err := strconv.ParseInt("42", , )

Quick reference

import "strconv"

n, err := strconv.Atoi(s)

What it does

• Converts a base-10 string to int
• Returns (int, error)

Common pattern

n, err := strconv.Atoi(input)
if err != nil {
	// handle invalid input
}

With flag.Arg

arg := flag.Arg(0)
n, err := strconv.Atoi(arg)
if err != nil {
	// handle error
}

Valid examples

"0"
"42"
"-7"

Invalid examples

""
"abc"
"12.5"
"7px"

When to use

How do I convert a string to an int in Go?

Use strconv.Atoi:

n, err := strconv.Atoi(s)

What is the idiomatic way to parse flag.Arg(n) as an integer in Go?

Read the argument as a string, then call strconv.Atoi, and handle the error.

What happens if the string is not a valid integer?

strconv.Atoi returns an error. You should check err before using the result.

Can strconv.Atoi parse negative numbers?

Yes. For example, "-10" parses successfully.

Can strconv.Atoi parse floating-point values like "3.14"?

No. It only parses integer strings. Use strconv.ParseFloat for floating-point numbers.

Should I use Atoi or ParseInt?

Use Atoi for normal decimal string-to- conversion. Use when you need more control over base or bit size.

• strconv.ParseInt — related because it parses integers with configurable base and bit size.
• strconv.ParseFloat — related because it parses strings into floating-point numbers.
• flag package — related because command-line arguments often come from flag.Arg().
• error handling in Go — related because parsing functions return errors that must be checked.
• type conversion in Go — related because parsing is different from converting one numeric type to another.
• command-line arguments in Go — related because many programs parse text input from the terminal.
• input validation — related because successful parsing does not guarantee the value is acceptable.