Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 40 ยท Testing and Tooling

Debugging and Profiling

Find bugs and slow code in Julia: Revise for fast reloads, Infiltrator and Debugger for stepping, @profile and flame graphs, and tracking allocations.

Every program has two kinds of problems: it does the wrong thing, or it does the right thing too slowly. Julia has good tools for both, and most of them are ordinary packages you load from the REPL. You do not need to leave your session, because Julia's compile-on-demand design makes a long-running REPL the natural way to work.

This lesson walks through the everyday toolbox: printing and logging, Revise for editing without restarts, Infiltrator and Debugger for stopping inside a function, the Profile standard library for finding hot spots, and allocation tracking, because in Julia unexpected memory allocation is the most common reason for slow code. Julia is not installed on this site, so the Julia code is read-only. The runnable examples are Python stand-ins that show the same ideas: counting calls and measuring allocations.

Start with the simple tools

Before you reach for a debugger, try printing. @show prints an expression together with its value, which is handy because it labels itself:

JULIA
function area(w, h)
    @show w h
    return w * h
end

area(3, 4)
# w = 3
# h = 4
# 12

For messages you want to keep in the code but switch off, use the logging macros. @debug messages are hidden until you ask for them with an environment variable or from code:

JULIA
function step(x)
    @debug "stepping" x
    return x + 1
end

step(1)                       # prints nothing

ENV["JULIA_DEBUG"] = Main     # turn on @debug messages for the Main module
step(1)
# โ”Œ Debug: stepping
# โ”‚   x = 1
# โ”” @ Main REPL[1]:2

Three more helpers answer the question "what code is really running?":

  • @which f(args...) shows which method a call selects (see Multiple Dispatch).
  • @edit f(args...) opens the source of that method in your editor.
  • typeof(x) and @code_warntype f(x) reveal types, which matters for speed (more on that below and in How Julia Compiles Code).

Revise: edit without restarting

The slowest part of Julia development is restarting: every new session recompiles your code. Revise.jl removes most restarts. It watches your source files and applies your edits to the running session.

JULIA
using Revise            # load it first, before your own code

includet("mycode.jl")   # include and TRACK this file
# or, for a package you are developing:
using MyPackage         # tracked automatically when it is dev'd or on the load path

Now edit mycode.jl, save, and call the function again at the REPL: it runs the new definition. A few edits still need a restart, mainly changing a struct definition, because existing objects already have the old layout. If Revise cannot apply an edit it tells you at the next call.

A common trick is to put using Revise in your ~/.julia/config/startup.jl so it is always loaded.

A debugging toolbox

@show and logging Quick look at values.
Revise Reload edited code without a restart.
Infiltrator Drop into a REPL inside a function.
Debugger Step line by line and set breakpoints.
1 / 2

Stopping inside a function with Infiltrator

Infiltrator.jl is the lightweight way to look around mid-function. You add @infiltrate where you want to pause, run the code, and get a REPL prompt with all local variables in scope:

JULIA
using Infiltrator

function normalize(v)
    total = sum(v)
    @infiltrate                 # execution stops here
    return v ./ total
end

normalize([2.0, 3.0, 5.0])
# Infiltrating normalize(v::Vector{Float64}) at REPL[3]:4
# infil> total
# 10.0
# infil> v
# 3-element Vector{Float64}: ...
# infil> @continue

Inside the infil> prompt you can evaluate any expression, call @locals to print every local variable, @exfiltrate to copy locals into a global store (safehouse) for later study, and @continue to resume. @infiltrate cond pauses only when a condition is true, which is useful inside a loop. Because it only checks a flag when disabled, you can leave it in during development, but remove it before releasing.

Stepping with Debugger.jl

When you want to walk through the code line by line, use Debugger.jl. You start it with @enter (begin at the first line of a call) or @run (run until a breakpoint):

JULIA
using Debugger

@enter normalize([2.0, 3.0, 5.0])
# In normalize(v) at REPL[3]:1
#  1  function normalize(v)
# >2      total = sum(v)
#  3      return v ./ total
#  4  end
# About to run: (sum)([2.0, 3.0, 5.0])
# 1|debug>

The commands at the 1|debug> prompt are short:

Command What it does
n Run the next line in this function
s Step into the call about to run
finish Run until the current function returns
c Continue to the next breakpoint (or the end)
bt Print the call stack
up / down Move between stack frames
` Switch to compiled mode for evaluating expressions

Breakpoints are set with breakpoint(normalize) before @run, or with bp add inside the debugger. One caveat: the Debugger interprets your code instead of running compiled machine code, so it is slow on heavy loops. For long computations, narrow the problem to a small input first, or use Infiltrator.

Profiling: where does the time go?

Guessing which line is slow is usually wrong. The Profile standard library samples the running program: every millisecond or so it records the current call stack, and in the end the lines that appear in the most samples are the hot spots.

JULIA
using Profile

function work(n)
    s = 0.0
    for i in 1:n
        s += sqrt(i) + sin(i)
    end
    return s
end

work(10)                 # run once so compilation is not profiled
@profile work(50_000_000)
Profile.print(format = :flat, sortedby = :count)
Profile.clear()          # forget the samples before the next profile

Two rules matter. First, run the code once before profiling, otherwise the compiler dominates the samples. Second, the code must run long enough to collect samples (at least a fraction of a second). Profile.print produces a tree by default; format = :flat gives a sorted list.

For a picture, load a viewer. ProfileView.@profview work(50_000_000) opens an interactive flame graph, where the width of each bar is the share of samples and bars stacked on top are callees. In VS Code the Julia extension offers @profview inside the editor, and PProf.jl exports profiles for external tools. A wide bar high up the stack is your target.

Red or yellow bars in ProfileView often point at type instability (inferred as Any, requiring dynamic dispatch) or at garbage collection. When the flame graph shows gc, you are allocating too much.

Allocations

Allocation means asking the memory manager for a fresh block, and every one costs time plus later garbage-collection work. The first number to check is the allocation count printed by @time:

JULIA
v = rand(1000)

@time sum(v)                   # 0.000002 seconds
@time v .* 2                   # 0.000003 seconds (2 allocations: 7.9 KiB)
@time v .*= 2                  # 0.000002 seconds  (in place: no allocation)

(The exact times and sizes vary; the point is the allocation column.) Useful tools:

  • @allocated expr returns the bytes allocated, and @allocations expr the count (Julia 1.9+).
  • BenchmarkTools.@btime and @benchmark run a call many times and report the minimum, which hides one-time compile cost. Interpolate globals with $ as in @btime sum($v).
  • Profile.Allocs.@profile sample_rate = 0.1 f() records where allocations happen, with the types, and a viewer such as PProf shows them.
  • Starting Julia with --track-allocation=user writes .mem files next to your sources listing bytes allocated per line.
  • JET.jl (@report_opt f(x)) and Cthulhu.jl (@descend f(x)) find type instabilities that cause hidden allocations.

A function that allocates inside a hot loop is a common problem, and the usual fixes are the ones from Performance Tips: preallocate, use @views, and write in-place ! functions.

Python stand-ins

The Python standard library has similar tools. The first example counts calls, exactly as a profiler's call table would, for a recursive function, so you can see why memoization helps. The numbers are deterministic.

Python A profiler call table

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Julia's Profile counts samples rather than calls, but the idea is the same: find the function that dominates, then ask why. Now the allocation side: compare a loop that builds a new list on every step with one that reuses a single buffer. A small counter plays the role of Julia's @allocations.

Python Counting allocations

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In Julia the same contrast shows up as @allocated returning bytes for the first version and 0 for a correctly written in-place version.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does Revise.jl do?

    Revise watches tracked files and updates method definitions in the live session. Changing a struct definition is the main thing that still needs a restart.
  2. 2. Why should you call a function once before running @profile on it?

    The first call includes compilation. Profile the second and later calls to see the cost of the code itself.
  3. 3. What does @infiltrate do?

    Infiltrator drops you into an infil> prompt at that line. Use @continue to resume.
  4. 4. In a flame graph, what does a very wide bar high in the stack indicate?

    Width is the share of samples. Wide bars show where time is spent and are the first candidates for optimization.

Summary

  • Start with @show, @debug and @which; use Revise to avoid restarting Julia.
  • Infiltrator pauses inside a function for quick inspection; Debugger.jl steps through code with n, s, finish and breakpoints, but runs interpreted and slowly.
  • @profile samples the call stack; run the code once first, then read Profile.print or a flame graph.
  • Allocation counts from @time, @allocated and Profile.Allocs often explain slow code; fix them with preallocation and in-place operations.
  • Use JET and Cthulhu to find type instabilities behind hidden allocations.

Next: reuse code from other ecosystems with Calling Python, C and R.