Tcl variable Command

last modified October 20, 2026

The Tcl variable command creates and links namespace variables. Inside a namespace it creates them; inside a procedure it links a local name to the variable of the same name in the namespace where the procedure is defined. This prevents confusion with local variables and global names.

Basic Definition

The variable command creates one or more variables in the current namespace and, inside a procedure, makes them visible under their short names. It's particularly important for procedures that need to access namespace variables.

Syntax: variable ?name value...? name ?value?. It can declare multiple variables at once. Without a value, the variable is only declared: it exists in the namespace but has no value, and info exists still returns 0 until it is set.

Basic Variable Declaration

This shows the simplest usage of variable to declare a variable.

basic_variable.tcl

variable name "John Doe"
puts $name

This declares a variable name with the value "John Doe". The puts command then prints the variable's value. This is similar to set but with namespace awareness. At the top level, the current namespace is the global namespace, so this creates the global variable ::name.

Global Variable Access

In a procedure defined in the global namespace, the variable command links to a global variable.

variable_global.tcl

set counter 0

proc increment {} {
    variable counter
    incr counter
}

increment
puts $::counter

Here we create a global variable counter and access it inside the increment procedure using variable. The procedure is defined in the global namespace, so variable counter links the local name to ::counter. In the global namespace global does the same job and is the more usual choice; the variable command is aimed at procedures inside namespaces.

Namespace Variables

variable is the standard way to work with namespace variables.

variable_namespace.tcl

namespace eval math {
    variable PI 3.14159
    
    proc area {radius} {
        variable PI
        expr {$PI * $radius * $radius}
    }
}

puts [math::area 5]

This creates a namespace math with a variable PI (Tcl has no constants). The area procedure accesses PI using variable; without that line, $PI would refer to a missing local variable and fail. Callers outside the namespace do not have to know the variable, although it can still be reached as $math::PI.

Multiple Variable Declaration

variable can declare multiple variables in one command.

variable_multiple.tcl

namespace eval config {
    variable width 800 height 600 title "App"
    
    proc show {} {
        variable width
        variable height
        variable title
        puts "Config: $width x $height, $title"
    }
}

config::show

This declares three variables in the config namespace at once. The show procedure declares each of them with its own variable command, because variable treats its arguments as name and value pairs; a single call such as variable width height title would assign the value height to width.

Variable Without Initialization

variable can declare a variable without assigning a value.

variable_declare.tcl

proc process {} {
    variable result
    set result "Operation completed"
    return $result
}

puts [process]
puts "Global result exists: [info exists ::result]"

Here we declare result without initialization inside a procedure. The variable is later assigned a value with set. Despite the declaration being inside the procedure, result is not a local variable: it is a variable of the procedure's namespace (here the global one), so it still exists after the procedure returns, as the second line of output shows. Use plain set for procedure-local variables.

Combining with upvar

variable can be combined with upvar for advanced variable handling.

variable_upvar.tcl

namespace eval outer {
    variable data "Important information"
    
    proc access {} {
        variable data
        upvar 0 data localdata
        puts "Accessed: $localdata"
        set localdata "Modified"
    }
}

outer::access
puts "After: $outer::data"

This demonstrates combining variable with upvar to create an alias to a namespace variable. The access procedure can work with the variable through a local name; upvar 0 links the name to a variable in the current scope. Changing the alias changes the namespace variable.

Best Practices

Namespace use: Always use variable for namespace variables.
Global access: Use global to reach globals from a namespace procedure; variable refers to the procedure's own namespace.
Early declaration: Declare variables at procedure start.
Explicit names: Use fully qualified names when needed.
Initialization: Give namespace variables an initial value in the namespace eval body, so that procedures do not fail on an unset variable.

This tutorial covered the Tcl variable 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