Bash – Check if variable is set

Bash – Check if variable is set

To check if a variable is set in Bash Scripting, the most direct expression is [[ -v variableName ]]. It returns true when the variable exists, even if the variable value is an empty string. For scripts that need to work with older Bash versions, you can also use parameter expansion such as [[ -n ${variableName+x} ]].

Do not confuse “set” with “not empty”. A variable can be set and still contain an empty value. For example, name="" means the variable name is set, but its value is empty. This difference matters when you validate script arguments, environment variables, configuration values, and values loaded from another script file.

In this tutorial, we shall learn the syntax and usage of the above mentioned expressions with examples.

Bash syntax to check whether a variable is set

Following is the syntax of boolean expressions which check if the variable is set:

  [[ -v variableName ]]

  [[ -z variableName ]]

The recommended Bash test for “variable exists” is [[ -v variableName ]]. The variable name is written without $. The expression checks whether the variable itself is set, not whether its value is non-empty.

The -z operator checks whether a string has zero length. Therefore, [[ -z ${variableName} ]] is useful for checking whether a variable expands to an empty value, but it does not reliably tell the difference between an unset variable and a variable that is set to an empty string.

[[ -v variableName ]]          # true if variableName is set
[[ -n ${variableName+x} ]]     # true if variableName is set
[[ -z ${variableName+x} ]]     # true if variableName is not set
[[ -z ${variableName} ]]       # true if value is empty or variable is unset

Difference between set, unset, and empty Bash variables

The following table shows how Bash treats common variable states.

Variable state	Example	[[ -v var ]]	[[ -z ${var} ]]	Meaning
Unset variable	unset var	false	true	The variable does not exist.
Set but empty	var=""	true	true	The variable exists, but its value is empty.
Set with value	var="abc"	true	false	The variable exists and has a non-empty value.

Use -v when your script needs to know whether a variable was declared or assigned. Use -z when your script needs to know whether the value is empty after expansion.

Example 1 – Check if Variable is Set using -v

In this example, we use [[ -v variableName ]] boolean expression to check if variables a and b are set with the help of bash if else statement.

Bash Script File

#!/bin/bash

a=10

# a: variable is set
if [[ -v a ]];
then
	echo "variable named a is already set"
else
	echo "variable a is not set"
fi

# b: variable is not set
if [[ -v b ]];
then
	echo "variable named b is already set"
else
	echo "variable b is not set"
fi

Output

~/workspace/bash$ ./bash-if-variable-is-set-example 
variable named a is already set
variable b is not set

Variable a is defined and assigned a value of 10 and hence is set. For variable b, we have not defined it by assigning a value. So, we got the result that variable b is not set.

Example 2 – Check if Variable is Set using -z

In this example, we use [[ -z ${variableName} ]] boolean expression to check if variables a and b are set with the help of bash if else  statement.

Bash Script File

#!/bin/bash

a=10

# a: variable is set
if [[ -z ${a} ]];
then
	echo "variable a is not set"
else
	echo "variable named a is already set"
fi

# b: variable is not set
if [[ -z ${b} ]];
then
	echo "variable b is not set"
else
	echo "variable named b is already set"
fi

Output

~/workspace/bash$ ./bash-if-variable-is-set-example 
variable named a is already set
variable b is not set

This example works for a=10 and an unset b. However, keep in mind that -z checks whether the expanded value is empty. If a were assigned as a="", then [[ -z ${a} ]] would be true even though a is set. For this reason, prefer [[ -v a ]] when the question is specifically whether the variable is set.

Bash check if variable is set but empty

Sometimes you need to check two things separately: whether the variable exists, and whether its value is empty. The following script checks both conditions.

#!/bin/bash

username=""

if [[ -v username ]]; then
    echo "username is set"
else
    echo "username is not set"
fi

if [[ -z ${username} ]]; then
    echo "username value is empty"
else
    echo "username value is not empty"
fi

Output

username is set
username value is empty

This is the important distinction: a variable assigned as username="" is set, but its value has zero length.

Bash check if environment variable is set

The same checks can be used for environment variables. For example, a script may require JAVA_HOME, PATH, API_KEY, or another configuration variable before it can continue.

#!/bin/bash

if [[ -v JAVA_HOME ]]; then
    echo "JAVA_HOME is set to: $JAVA_HOME"
else
    echo "JAVA_HOME is not set"
fi

If the environment variable must also contain a non-empty value, check both conditions.

#!/bin/bash

if [[ -v API_KEY && -n ${API_KEY} ]]; then
    echo "API_KEY is set and not empty"
else
    echo "API_KEY is missing or empty"
fi

Bash-compatible way to check if a variable is set

If you do not want to depend on [[ -v variableName ]], use parameter expansion with +x. This checks whether the variable is set without depending on the variable’s actual value.

#!/bin/bash

color=""

if [[ -n ${color+x} ]]; then
    echo "color is set"
else
    echo "color is not set"
fi

Output

color is set

Here, color is set even though it contains an empty string. The expression ${color+x} expands to x only when color is set. If color is unset, it expands to an empty string.

Bash variable set checks in script validation

A practical use case is to stop a script early when a required variable has not been set. This is common in deployment scripts, backup scripts, build scripts, and command-line tools that read configuration from the environment.

#!/bin/bash

if [[ ! -v APP_ENV ]]; then
    echo "Error: APP_ENV is not set"
    exit 1
fi

echo "Running app in $APP_ENV environment"

If an empty value should also be rejected, use -z after confirming the variable exists, or combine the logic in one condition.

#!/bin/bash

if [[ ! -v APP_ENV || -z ${APP_ENV} ]]; then
    echo "Error: APP_ENV is not set or is empty"
    exit 1
fi

echo "Running app in $APP_ENV environment"

Common mistakes when checking Bash variables

• Do not write [[ -v $var ]] when you want to check the variable named var. Use [[ -v var ]] without the dollar sign.
• Do not use only [[ -z ${var} ]] when you must distinguish between unset and empty. It is true for both cases.
• Do not assume that an empty value means the variable is unset. var="" creates a set variable with an empty value.
• Use unset var when you want to remove a variable completely.
• Quote variable expansions when using single brackets, such as [ -z "$var" ]. In [[ ... ]], Bash handles word splitting more safely, but quoting is still often used for clarity.

Frequently asked questions about checking whether a Bash variable is set

How do I check if a variable is set in Bash?

Use [[ -v variableName ]]. For example, [[ -v username ]] returns true if the variable named username exists, even when its value is empty.

How do I check if a Bash variable is not set?

Use the negation operator with -v: [[ ! -v variableName ]]. You can also use [[ -z ${variableName+x} ]], which is true when the variable is unset.

What is the difference between -v and -z in Bash?

-v checks whether a variable is set. -z checks whether a string has zero length. Therefore, -z is an empty-value check, not a reliable set-variable check by itself.

How do I check if a variable is set and not empty in Bash?

Use both checks together: [[ -v variableName && -n ${variableName} ]]. This returns true only when the variable exists and expands to a non-empty value.

How do I unset a Bash variable before testing it?

Use unset variableName. After that, [[ -v variableName ]] returns false because the variable no longer exists in the current shell.

Editorial QA checklist for Bash variable set examples

• Verify that examples using -v pass the variable name without $.
• Check that the tutorial clearly separates “unset variable” from “set but empty variable”.
• Confirm that -z examples are described as empty-string checks, not always as set-variable checks.
• Include at least one environment-variable example, because many users search for this topic while validating script configuration.
• Test output text for all examples where unset, empty, and non-empty values are compared.

Conclusion

In this Bash Tutorial, we have learnt to check if a variable is set or not using [[ -v variableName ]] or [[ -z ${variableName} ]], with the help of example Bash scripts. In practical Bash scripts, prefer [[ -v variableName ]] when you need to know whether the variable exists, and use [[ -z ${variableName} ]] only when you want to test whether the variable value is empty.