Tcl auto_load Command

last modified October 20, 2026

The Tcl auto_load command is part of Tcl's auto-loading mechanism. Tcl procedures defined in library files are loaded the first time they are called. This provides on-demand loading of procedures, not of packages (those are loaded with package require).

Basic Definition

The auto_load command checks if a command exists and attempts to load it if not found. It uses the auto_index array, which is built from tclIndex files found in the auto_path directories, to locate and source the script that defines the command.

Syntax: auto_load cmdName ?namespace?. The command returns 1 if it found a definition in the index and loaded it, and 0 otherwise. It returns 0 for built-in commands such as puts, because they have no index entry.

Basic auto_load Usage

This example shows the simplest usage of auto_load to attempt loading a command.

basic_auto_load.tcl

if {[auto_load some_command]} {
    puts "Attempted to load some_command"
} else {
    puts "some_command not found in auto_load index"
}

This checks if some_command can be loaded automatically. Since no index entry exists for it, auto_load returns 0 and the else branch runs. The message in the if branch would therefore be better read as "loaded", since 1 means the definition was found and sourced.

Checking Command Existence

Combine auto_load with info commands to verify if a command was successfully loaded.

auto_load_check.tcl

set cmdName "my_proc"
auto_load $cmdName
if {[info commands $cmdName] ne ""} {
    puts "$cmdName is now available"
} else {
    puts "Failed to load $cmdName"
}

This attempts to load my_proc and checks if it exists afterward. The info commands verifies the command's availability.

Loading Standard Library Commands

Many Tcl standard library commands use auto-loading. This example demonstrates loading the file command.

auto_load_stdlib.tcl

if {[llength [info commands file]] == 0} {
    auto_load file
    puts "Attempted to load file command"
}
file exists /tmp

This checks if the file command exists, attempts to load it if not, then uses it. file is a built-in command, so it always exists and the body of the if never runs; the script prints nothing. Only procedures defined in Tcl library scripts are loaded through the index.

Working with Custom Packages

For your own procedures, add their directory to auto_path and create a tclIndex file there with auto_mkindex.

auto_load_custom.tcl

lappend auto_path [file join $env(HOME) my_tcl_libs]
if {[auto_load my_custom_proc]} {
    my_custom_proc
} else {
    puts "Could not load my_custom_proc"
}

This adds a custom library directory to auto_path then attempts to load a procedure from it. The procedure must be listed in the tclIndex file of that directory. The directory and procedure in this example do not exist, so the script prints "Could not load my_custom_proc".

Auto Loading with Namespaces

auto_load works with namespaced commands too. This example shows how to load a namespaced command.

auto_load_namespace.tcl

if {[auto_load ::mylib::myfunc]} {
    puts "Loaded ::mylib::myfunc"
    ::mylib::myfunc
}

This attempts to load a command from the mylib namespace. The index must contain the fully qualified name ::mylib::myfunc. With no such index entry the script prints nothing.

Debugging Auto Loading

Use auto_qualify and the auto_index array to debug auto-loading issues.

auto_load_debug.tcl

set cmd "my_command"
set qualified [auto_qualify $cmd ""]
puts "Looking for: $qualified"
parray auto_index

The auto_index array holds the commands that can be loaded on demand, and parray prints it (the output is long, because Tcl's own library registers many entries). The auto_qualify command takes a command name and a namespace and returns the fully qualified name Tcl looks up, followed by the unqualified one; here it prints "::my_command my_command".

Best Practices

Setup: Add library directories to auto_path before calling their procedures.
Indexing: Regenerate tclIndex with auto_mkindex whenever a library file changes.
Namespaces: Put library procedures in a namespace to avoid name conflicts.
Packages: For larger libraries prefer package require with a pkgIndex.tcl file.
Cache: Call auto_reset after changing the index at run time.

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