Tcl auto_reset Command

last modified October 20, 2026

The Tcl auto_reset command discards the cached information used by the autoloader. After the reset, Tcl rebuilds this cache from the directories in auto_path the next time it needs it. It is useful after libraries have been added or changed while a program is running.

Basic Definition

Tcl autoloading finds commands that are not yet defined by reading tclIndex files in the directories listed in the global auto_path variable. The result is cached in the auto_index array, and the locations of external programs found by auto_execok are cached in auto_execs.

Syntax: auto_reset. The command takes no arguments and returns an empty string. It unsets the cached data, so the next autoload lookup reads the index files again.

Simple Reset

This example shows the basic use of the auto_reset command.

simple_reset.tcl

auto_reset
puts "Autoload cache cleared"

The command clears the autoload caches. It produces no output of its own, so the script only reports that it has run.

Clearing the auto_execok Cache

The auto_execok command remembers where it found an executable. This example shows that auto_reset forgets these entries.

execok_cache.tcl

auto_execok ls
puts "Cached before: [info exists ::auto_execs(ls)]"
auto_reset
puts "Cached after:  [info exists ::auto_execs(ls)]"

The first call to auto_execok stores the result for ls in the auto_execs array. After auto_reset, the entry is gone and the program is searched for again on the next call.

Autoloading a New Library

This example creates a small library at run time, indexes it, and makes Tcl aware of it.

new_library.tcl

set dir [file join [pwd] mylib]
file mkdir $dir

set fd [open [file join $dir hello.tcl] w]
puts $fd {proc hello {} {puts "Hello from an autoloaded proc"}}
close $fd

auto_mkindex $dir
lappend ::auto_path $dir
auto_reset

hello

The script writes hello.tcl, builds a tclIndex file with auto_mkindex, and adds the directory to auto_path. The call to auto_reset makes sure the index is read again, so the hello procedure is found and sourced on its first use.

auto_reset in Safe Interpreters

A safe interpreter does not get the auto_reset command, so it is not available there.

safe_interp_auto_reset.tcl

set safe [interp create -safe]
if {[catch {interp eval $safe auto_reset} msg]} {
    puts "Error: $msg"
}
interp delete $safe

The safe interpreter has no auto_reset command, so the call fails with an invalid command name error, which the script catches and prints.

Best Practices

Arguments: auto_reset takes none; it cannot be switched on or off.
When to call it: Call it after changing auto_path or rebuilding tclIndex files.
Cost: Avoid calling it in loops, because the caches have to be rebuilt.
Indexes: Create index files with auto_mkindex.
Packages: For larger libraries, prefer package require.

This tutorial covered the Tcl auto_reset command with practical examples showing how to clear the autoload caches.

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