Python linecache — Core Concepts

What linecache provides

The linecache module reads entire files into memory and lets you retrieve any line by number. It’s designed for situations where you need random access to file lines — particularly source code display in tracebacks, debuggers, and profilers.

Core API

The module has just four functions that matter:

linecache.getline(filename, lineno)

Returns the specified line (1-indexed) as a string including the trailing newline. Returns an empty string if the line doesn’t exist:

import linecache

line = linecache.getline("/etc/hostname", 1)
print(repr(line))  # 'myserver\n'

# Line that doesn't exist
missing = linecache.getline("/etc/hostname", 999)
print(repr(missing))  # ''

linecache.getlines(filename)

Returns all lines of the file as a list of strings. Useful when you need multiple lines:

lines = linecache.getlines("script.py")
# Show lines 10-15
for line in lines[9:15]:
    print(line, end="")

linecache.clearcache()

Removes all cached file contents from memory. Call this if files have changed on disk and you need fresh data:

linecache.clearcache()

linecache.checkcache(filename=None)

Checks whether cached entries are still valid (file hasn’t been modified). Discards stale entries. If filename is None, checks all cached files.

How the caching works

The first call to getline for a file reads the entire file into a module-level dictionary. Subsequent calls return from the cache — no disk I/O.

The cache structure internally looks like:

# linecache.cache[filename] = (size, mtime, lines, fullname)

This means:

• First access: ~1ms for a typical source file (disk read + split into lines)
• Subsequent access: ~0.1μs (dict lookup + list index)

Where Python uses linecache

Tracebacks

When Python prints a traceback, it uses linecache to show the source code of each frame:

Traceback (most recent call last):
  File "app.py", line 42, in process
    result = data["missing_key"]  ← linecache fetched this line
KeyError: 'missing_key'

The traceback module calls linecache.getline() for each frame in the stack.

The inspect module

inspect.getsource() and inspect.getsourcelines() use linecache to retrieve source code of functions, classes, and modules.

Debuggers and profilers

pdb, cProfile, and third-party tools like py-spy rely on linecache for source display.

Practical use case: error context display

import linecache

def show_context(filename, lineno, context=3):
    """Show lines around an error with line numbers."""
    start = max(1, lineno - context)
    end = lineno + context + 1
    lines = []
    for i in range(start, end):
        line = linecache.getline(filename, i)
        if not line:
            break
        marker = ">>>" if i == lineno else "   "
        lines.append(f"{marker} {i:4d} | {line}")
    return "".join(lines)

Memory considerations

linecache holds every file it reads in memory until you call clearcache(). For most applications this is fine — source files are small. But if you’re reading thousands of large files, the cache can grow:

• Typical Python source file: 5-50 KB
• 100 cached files: 0.5-5 MB
• If caching data files (not recommended): potentially much more

Call clearcache() periodically in long-running applications that process many files, or use checkcache() to prune only stale entries.

Common misconception

linecache isn’t a general-purpose file reader. It’s optimized for source-file-sized text files where you need random line access. For large data files, CSV processing, or streaming, use dedicated tools (csv, pandas, readline). linecache reads the entire file into memory, which is fine for a 50 KB source file but wasteful for a 2 GB log file.

One thing to remember

linecache is a “read once, access forever” line-retrieval cache that powers Python’s traceback display. Use it when you need random line access to source files, and call clearcache() if files change on disk.