Tcl unset Command

last modified October 20, 2026

The Tcl unset command is used to remove variables or array elements. It frees the memory of variables that are no longer needed and lets a script check later with info exists that a value is gone. The command can remove single variables or multiple variables at once.

Basic Definition

The unset command destroys one or more variables. Once unset, the variable no longer exists in the current scope. Attempting to access it will raise an error.

Syntax: unset ?-nocomplain? ?--? ?name name ...?. The optional -nocomplain suppresses errors for non-existent variables. Without it, unsetting a missing variable raises an error, and the names after the missing one are not processed.

Basic Variable Removal

This shows the simplest usage of unset to remove a single variable.

basic_unset.tcl

set name "John Doe"
puts "Before unset: $name"
unset name
puts "After unset: [info exists name]"

This creates a variable name, prints it, then removes it with unset. The info exists command checks if the variable still exists.

Removing Multiple Variables

The unset command can remove several variables in one operation.

unset_multiple.tcl

set x 10
set y 20
set z 30
puts "Before: x=$x, y=$y, z=$z"
unset x y z
puts "After: x exists? [info exists x]"

This creates three variables, then removes them all with one unset command. The example verifies removal by checking variable existence.

Unsetting Array Elements

unset can remove individual elements from an array while keeping the array intact.

unset_array.tcl

array set colors {
    red   #ff0000
    green #00ff00
    blue  #0000ff
}
puts "Before: [array get colors]"
unset colors(green)
puts "After: [array get colors]"

This creates an array of colors, then removes the green element. The remaining array elements are still accessible after the operation.

Using -nocomplain Option

The -nocomplain option prevents errors when unsetting non-existent variables.

unset_nocomplain.tcl

# This would normally cause an error
unset -nocomplain non_existent_var
puts "Command completed without error"

set temp_var "temporary"
unset -nocomplain temp_var non_existent_var
puts "Mixed unset completed"

This shows how -nocomplain allows the script to continue even when some variables don't exist. Useful for cleanup scripts.

Unsetting Variables in Procedures

A procedure can unset its local variables before it returns.

unset_proc.tcl

proc calculate {} {
    set a 5
    set b 10
    set result [expr {$a * $b}]
    unset a b
    return $result
}
puts "Result: [calculate]"

This procedure calculates a result, then unsets its temporary variables before returning. This is not required: local variables are removed automatically when the procedure returns, so unsetting them early only matters when a local variable holds a very large value and the procedure keeps running for a long time. Note that unset on a variable linked with global or upvar removes the variable it points to, not just the local link.

Unsetting Entire Arrays

The unset command can remove entire arrays with a single operation.

unset_whole_array.tcl

array set user {
    name John
    age 30
    city {New York}
}
puts "Before: [array exists user]"
unset user
puts "After: [array exists user]"

This creates an array, then removes it completely. The array exists command verifies the array's existence before and after unset.

Best Practices

Cleanup: Unset large variables when no longer needed.
Scope: unset works on the variable visible in the current scope; inside a procedure use unset ::name or global to reach a global variable.
Arrays: unset arr removes the whole array, while unset arr(key) removes one element.
Safety: Use -nocomplain for optional cleanup.
Checking: Use info exists before accessing a variable that may have been unset.

This tutorial covered the Tcl unset command with practical examples showing its usage in different scenarios.

Author

My name is Jan Bodnar, and I am a passionate programmer with extensive programming experience. I have been writing programming articles since 2007. To date, I have authored over 1,400 articles and 8 e-books. I possess more than ten years of experience in teaching programming.

List all Tcl Tutorials.

Ebooks