These instructions are applicable only for Julia 1.5 and higher. If you are running an older version of Julia, upgrading to at least 1.6 is recommended. If you cannot upgrade, see the documentation for Revise 3.2.x or earlier.
Using Revise by default
If you like Revise, you can ensure that every Julia session uses it by launching it from your
~/.julia/config/startup.jl file. Note that using Revise adds a small latency at Julia startup, generally about 0.7s when you first launch Julia and another 0.25s for your first package load. Users should weigh this penalty against whatever benefit they may derive from not having to restart their entire session.
This can be as simple as adding
as the first line in your
startup.jl. If you have a Unix terminal available, simply run
mkdir -p ~/.julia/config/ && echo "using Revise" >> ~/.julia/config/startup.jl
If you use different package environments and do not always have Revise available,
try using Revise catch e @warn "Error initializing Revise" exception=(e, catch_backtrace()) end
is recommended instead.
Using Revise automatically within Jupyter/IJulia
If you want Revise to launch automatically within IJulia, then you should also create a
.julia/config/startup_ijulia.jl file with the contents
try @eval using Revise catch e @warn "Error initializing Revise" exception=(e, catch_backtrace()) end
or simply run
mkdir -p ~/.julia/config/ && tee -a ~/.julia/config/startup_ijulia.jl << END try @eval using Revise catch e @warn "Error initializing Revise" exception=(e, catch_backtrace()) end END
Configuring the revise mode
By default, in packages all changes are tracked, but with
includet only method definitions are tracked. This behavior can be overridden by defining a variable
__revise_mode__ in the module(s) containing your methods and/or data.
__revise_mode__ must be a
Symbol taking one of the following values:
:eval: evaluate everything (the default for packages)
:evalmeth: evaluate changes to method definitions (the default for
includet) This should work even for quite complicated method definitions, such as those that might be made within a
:evalassign: evaluate method definitions and assignment statements. A top-level expression
a = Intwould be evaluated, but
push!(a, 1)would not because the latter is not an assignment.
:sigs: do not implement any changes, only scan method definitions for their signatures so that their location can be updated as changes to the file(s) are made.
If you're using
includet from the REPL, you can enter
__revise_mode__ = :eval to set it throughout
__revise_mode__ can be set independently in each module.
Optional global configuration
Revise can be configured by setting environment variables. These variables have to be set before you execute
using Revise, because these environment variables are parsed only during execution of Revise's
There are several ways to set these environment variables:
- If you are Using Revise by default then you can include statements like
ENV["JULIA_REVISE"] = "manual"in your
.julia/config/startup.jlfile prior to the line containing
- On Unix systems, you can set variables in your shell initialization script (e.g., put lines like
export JULIA_REVISE=manualin your
.bashrcfile if you use
- On Unix systems, you can launch Julia from the Unix prompt as
$ JULIA_REVISE=manual juliato set options for just that session.
The function of specific environment variables is described below.
Manual revision: JULIA_REVISE
By default, Revise processes any modified source files every time you enter a command at the REPL. However, there might be times where you'd prefer to exert manual control over the timing of revisions.
Revise looks for an environment variable
JULIA_REVISE, and if it is set to anything other than
"auto" it will require that you manually call
revise() to update code.
User scripts: JULIA_REVISE_INCLUDE
Revise only tracks files that have been required as a consequence of a
import statement; files loaded by
include are not tracked, unless you explicitly use
Revise.track(filename). However, you can turn on automatic tracking by setting the environment variable
JULIA_REVISE_INCLUDE to the string
JULIA_REVISE_INCLUDE=1 in a bash script).
Most users should avoid setting
Configurations for fixing errors
No space left on device
This applies only to Linux
Revise needs to be notified by your filesystem about changes to your code, which means that the files that define your modules need to be watched for updates. Some systems impose limits on the number of files and directories that can be watched simultaneously; if this limit is hit, on Linux this can result in a fairly cryptic error like
ERROR: start_watching (File Monitor): no space left on device (ENOSPC)
The cure is to increase the number of files that can be watched, by executing
echo 65536 | sudo tee -a /proc/sys/fs/inotify/max_user_watches
at the Linux prompt. (The maximum value is 524288, which will allocate half a gigabyte of RAM to file-watching). For more information see issue #26.
Changing the value this way may not last through the next reboot, but you can also change it permanently.
Polling and NFS-mounted code directories: JULIA_REVISE_POLL
This applies only to Unix systems with code on network-mounted drives
Revise works by monitoring your filesystem for changes to the files that define your code. On most operating systems, Revise can work "passively" and wait to be signaled that one or more watched directories has changed.
Unfortunately, a few file systems (notably, the Unix-based Network File System NFS) don't support this approach. In such cases, Revise needs to "actively" check each file periodically to see whether it has changed since the last check. This active process is called polling. You turn on polling by setting the environment variable
JULIA_REVISE_POLL to the string
JULIA_REVISE_POLL=1 in a bash script).
If you're using polling, you may have to wait several seconds before changes take effect. Polling is not recommended unless you have no other alternative.
NFS stands for Network File System and is typically only used to mount shared network drives on Unix file systems. Despite similarities in the acronym, NTFS, the standard filesystem on Windows, is completely different from NFS; Revise's default configuration should work fine on Windows without polling. However, WSL2 users currently need polling due to this bug.