Engee documentation

Environment variables

Julia can be configured using a number of environment variables, set either in the usual way for each operating system, or in a portable way in Julia. If, for example, the environment variable JULIA_EDITOR you need to set the value to vim', you can enter `ENV["JULIA_EDITOR"] = "vim" (for example, in REPL) to make this change on a case-by-case basis, or add the same to the user’s configuration file ~/.julia/config/startup.jl in the user’s home directory to achieve a permanent effect. The current value of the same environment variable can be found by checking ENV["JULIA_EDITOR"].

The environment variables used in Julia usually start with JULIA'. If `InteractiveUtils.versioninfo is called with the keyword verbose=true', the output will contain all defined environment variables suitable for Julia, including those that contain `JULIA in their names.

It is recommended to avoid changing environment variables at runtime, for example inside ~/.julia/config/startup.jl.

One reason is that some Julia language variables, such as [JULIA_NUM_THREADS'](environment-variables.md#JULIA_NUM_THREADS) and [`JULIA_PROJECT](environment-variables.md#JULIA_PROJECT), must be set before Julia is launched.

Similarly, the functions __init__() Creating custom modules in sysimage (via via PackageCompiler) should be done before `startup.jl, so setting environment variables in startup.jl may be too late for custom code.

In addition, changing environment variables at runtime can lead to data races in otherwise safe code.

In Bash, environment variables can be set manually by running, for example, the command export JULIA_NUM_THREADS=4 before running Julia, or by adding the same command to ~/.bashrc or ~/.bash_profile for setting a variable each time Bash is started.

File Locations

JULIA_BINDIR

The absolute path to the directory containing the Julia executable file, which sets the global variable Sys.BINDIR. If the variable $JULIA_BINDIR is not set, Julia determines the value of Sys.BINDIR at runtime.

The executable file itself is one of

$JULIA_BINDIR/julia
$JULIA_BINDIR/julia-debug

by default.

The global variable Base.DATAROOTDIR defines the relative path from Sys.BINDIR to the data directory associated with Julia. Then the path

$JULIA_BINDIR/$DATAROOTDIR/julia/base

defines the directory where Julia initially searches for the source files (using Base.find_source_file()).

Similarly, the global variable Base.SYSCONFDIR defines the relative directory path of the configuration file. Julia then searches for the startup.jl file in

$JULIA_BINDIR/$SYSCONFDIR/julia/startup.jl
$JULIA_BINDIR/../etc/julia/startup.jl

by default (using Base.load_julia_startup()).

For example, in a Linux installation with the Julia executable located in /bin/julia, the variable DATAROOTDIR for ../share and the variable SYSCONFDIR for ../etc JULIA_BINDIR will have the value /bin, the search path of the source code file

/share/julia/base

and the global configuration search path

/etc/julia/startup.jl

JULIA_PROJECT

The path to the directory that specifies which project should be the initial active project. Setting this environment variable is similar to specifying the startup parameter --project, but --project has a higher priority. If the variable is set to @. (note the dot at the end), Julia is trying to find the project directory containing the file Project.toml or JuliaProject.toml from the current directory and its parent directories. See also the chapter Code download.

JULIA_PROJECT should be defined before Julia is launched. It is too late to define this variable in the startup.jl file during startup.

JULIA_LOAD_PATH

Environment variable JULIA_LOAD_PATH' is used to fill in the Julia global variable `LOAD_PATH', which determines which packages can be loaded by `importing and using (see the chapter Code download).

Unlike the shell’s PATH variable, empty entries in JULIA_LOAD_PATH are expanded to the default value of LOAD_PATH``"@", "@v#.#", "@stdlib"] when filling in the LOAD_PATH'. This makes it easy to add the load value to the end or beginning of shell scripts, regardless of whether the variable is set. `JULIA_LOAD_PATH' or not yet. For example, to add the directory `/foo/bar to the beginning of the LOAD_PATH variable, simply run

export JULIA_LOAD_PATH="/foo/bar:$JULIA_LOAD_PATH"

If the environment variable is JULIA_LOAD_PATH has already been set, and /foo/bar' will be added to the beginning of its old value. On the other hand, if the variable `JULIA_LOAD_PATH' is not set, it will be set to `/foo/bar:, which will expand the value of LOAD_PATH to ["/foo/bar", "@", "@v#.#", "@stdlib"]. If as the value of a variable JULIA_LOAD_PATH' an empty string is set, it expands to an empty array `LOAD_PATH'. In other words, an empty string is interpreted as a zero-element array, not as a one-element array of an empty string. This behavior was chosen so that an empty boot path could be set using an environment variable. If you need the default download path, either cancel the value of the environment variable, or, if it should have a value, set the string `: as its value.

In Windows, path elements are separated by the ; character, as in most Windows path lists. Replace the : with the ; in the paragraph above.

JULIA_DEPOT_PATH

Environment variable JULIA_DEPOT_PATH is used to fill in the Julia global variable `DEPOT_PATH', which controls where the package manager and Julia code download mechanisms search for package registries, installed packages, named environments, repository clones, cached compiled package images, configuration files, and the default location of the REPL history file.

Unlike the shell’s PATH variable, but similarly JULIA_LOAD_PATH, empty entries in JULIA_DEPOT_PATH have a special behavior.

  • At the end, it expands to the default value of DEPOT_PATH, excluding custom storage.

  • At the beginning, it expands to the default value of DEPOT_PATH, including custom storage. This makes it easy to redefine user storage, while maintaining access to resources supplied with Julia, such as cache files, artifacts, etc. For example, to switch user storage to /foo/bar, use the end character :.

export JULIA_DEPOT_PATH="/foo/bar:"

All operations with packages, such as cloning registries or installing packages, will now be recorded in /foo/bar, but since the empty record expands to the default system storage, any associated resources will still be available. If you really want to use only the storage along the path /foo/bar and not download resources as part of Julia, just set the environment variable to /foo/bar without a colon at the end.

To add storage to the end of the full default list, including the default user storage, use the initial character :.

export JULIA_DEPOT_PATH=":/foo/bar"

The above rule has two exceptions. The first is if the value of the variable is `JULIA_DEPOT_PATH' an empty string is set, it expands to an empty array `DEPOT_PATH'. In other words, an empty string is interpreted as a zero-element array, not as a one-element array of an empty string. This behavior was chosen so that an empty storage path could be set using an environment variable.

The second is if in JULIA_DEPOT_PATH no user storage is specified, then the empty record is expanded to the default storage, including user storage. This allows you to use the default storage as if the environment variable had not been set by setting the string : for it.

In Windows, path elements are separated by the ; character, as in most Windows path lists. Replace the : with the ; in the paragraph above.

JULIA_DEPOT_PATH should be defined before Julia is started. It is too late to define this variable in the startup.jl file during startup. In this case, you can instead directly change the DEPOT_PATH array, which is filled in from the environment variable.

JULIA_HISTORY

The absolute path of the REPL.find_hist_file() to the REPL history file. If the value of $JULIA_HISTORY is not set, REPL.find_hist_file() uses by default

$(DEPOT_PATH[1])/logs/repl_history.jl

JULIA_MAX_NUM_PRECOMPILE_FILES

Sets the maximum number of different instances of a single package that will be stored in the pre-compilation cache (10 by default).

JULIA_VERBOSE_LINKING

If set to true, linker commands will be output during pre-compilation.

Pkg.jl

JULIA_CI

A set value of true indicates to the package server that any operations with packages are part of a continuous integration (CI) system for the purpose of collecting package usage statistics.

JULIA_NUM_PRECOMPILE_TASKS

The number of parallel tasks to use when pre-compiling packages. See the description https://pkgdocs.julialang.org/v1/api/#Pkg.precompile [Pkg.precompile].

JULIA_PKG_DEVDIR

The default directory used by https://pkgdocs.julialang.org/v1/api/#Pkg.develop [Pkg.develop] for downloading packages.

JULIA_PKG_IGNORE_HASHES

If the value is set to `1', incorrect hashes in artifacts will be ignored. This method should be used carefully, as it disables download verification, but allows you to solve problems when moving files in different types of file systems. For more information, see the about page https://github.com/JuliaLang/Pkg.jl/issues/2317 [the Pkg problem.jl № 2317].

Compatibility: Julia 1.6

It is supported in Julia 1.6 and later versions.

JULIA_PKG_OFFLINE

If the value is set to true', offline mode will be enabled: see the description https://pkgdocs.julialang.org/v1/api/#Pkg.offline [`Pkg.offline].

Compatibility: Julia 1.5

Pkg offline mode requires Julia 1.5 or later.

JULIA_PKG_PRECOMPILE_AUTO

If the value is set to 0', automatic pre-compilation performed by package actions will be disabled, which will change the manifest. See the description https://pkgdocs.julialang.org/v1/api/#Pkg.precompile [`Pkg.precompile].

JULIA_PKG_SERVER

Specifies the URL of the package registry used. By default, Pkg uses +https://pkg.julialang.org + to extract Julia packages. In addition, you can disable the PkgServer protocol and access packages directly from their hosts (GitHub, GitLab, etc.) by setting export JULIA_PKG_SERVER="".

JULIA_PKG_SERVER_REGISTRY_PREFERENCE

Specifies the preferred registry type. Currently, conservative values are supported (by default), which means that only those resources that have been processed by the storage server (and thus have a higher chance of access from PkgServers) will be published, while eager will publish registries whose resources have not necessarily been processed by the servers. storage facilities. Users who are behind restrictive firewalls that do not allow downloads from arbitrary servers should not use the eager type.

Compatibility: Julia 1.7

This applies only to Julia 1.7 and later versions.

JULIA_PKG_UNPACK_REGISTRY

If set to `true', the registry will be unpacked rather than saved as a compressed Tarball archive.

Compatibility: Julia 1.7

This applies only to Julia 1.7 and later versions. In earlier versions, the registry is always unpacked.

JULIA_PKG_USE_CLI_GIT

If set to true, Pkg operations using the git protocol will work with the external executable file `git', and not with the default libgit2 library.

Compatibility: Julia 1.7

The use of the git executable file is supported only in Julia 1.7 and later versions.

JULIA_PKGRESOLVE_ACCURACY

The accuracy of the packet comparator. This must be a positive integer, and 1 is used by default.

JULIA_PKG_PRESERVE_TIERED_INSTALLED

Changes the default package installation strategy to Pkg.PRESERVE_TIERED_INSTALLED so that the package manager tries to install package versions, saving as many versions of already installed packages as possible.

Compatibility: Julia 1.9

This applies only to Julia 1.9 and later versions.

Network transport

JULIA_NO_VERIFY_HOSTS

JULIA_SSL_NO_VERIFY_HOSTS

JULIA_SSH_NO_VERIFY_HOSTS

JULIA_ALWAYS_VERIFY_HOSTS

Specifies nodes whose IDs should or should not be checked for certain transport levels. See the description https://github.com/JuliaLang/NetworkOptions.jl#verify_host [NetworcOptions.verify_host].

JULIA_SSL_CA_ROOTS_PATH

Specifies the file or directory containing the certificate authority’s roots. See the description https://github.com/JuliaLang/NetworkOptions.jl#ca_roots [NetworcOptions.ca_roots]

link:@id External-applications[External applications].

JULIA_SHELL

The absolute path to the shell that Julia should use to execute external commands (via Base.repl_cmd()). By default, the environment variable $SHELL is used, and if the $SHELL variable is not specified, /bin/sh is used.

On Windows, this environment variable is ignored and external commands are executed directly.

JULIA_EDITOR

The editor returned by InteractiveUtils.editor() and used, for example, in the method InteractiveUtils.edit, referring to the command of the preferred editor, for example `vim'.

'$JULIA_EDITOR` takes precedence over the $VISUAL variable, which in turn takes precedence over $EDITOR'. If none of these environment variables are set, the editor is considered `open on Windows and OS X, or /etc/alternatives/editor if it exists, or emacs otherwise.

To use Visual Studio Code in Windows, set the variable $JULIA_EDITOR to `code.cmd'.

Parallelization

JULIA_CPU_THREADS

Redefines a global variable Base.Sys.CPU_THREADS, the number of available logical CPU cores.

JULIA_WORKER_TIMEOUT

Type Float64, which sets the value for Distributed.worker_timeout()' (default is `60.0). This function sets the number of seconds that the workflow will wait for the main process to establish a connection before terminating.

JULIA_NUM_THREADS

An unsigned 64-bit integer ('uint64_t') specifying the maximum number of threads available for Julia. If the value of $JULIA_NUM_THREADS is not positive or is not set, or if the number of CPU threads cannot be determined using system calls, the number of threads is set to `1'.

If $JULIA_NUM_THREADS is set to auto, the number of threads will be set to the number of processor threads.

JULIA_NUM_THREADS should be defined before Julia is launched. It is too late to define this variable in the startup.jl file during startup.

Compatibility: Julia 1.5

In Julia 1.5 and later, the number of threads can also be set at startup using the command line argument -t (--threads).

Compatibility: Julia 1.7

To set the auto value for the $JULIA_NUM_THREADS variable, Julia 1.7 or later versions are required.

JULIA_THREAD_SLEEP_THRESHOLD

If a string is specified that starts with the case-independent substring "infinite", alternating streams never enter sleep mode. Otherwise, $JULIA_THREAD_SLEEP_THRESHOLD is interpreted as an unsigned 64-bit integer (`uint64_t') and allocates (in nanoseconds) the amount of time after which alternating threads should go to sleep.

JULIA_NUM_GC_THREADS

Sets the number of threads used during garbage collection. If no value is specified, half the number of worker threads is set.

Compatibility: Julia 1.10

The environment variable was added in version 1.10.

JULIA_IMAGE_THREADS

An unsigned 32-bit integer specifying the number of streams used when compiling the image in this Julia process. The value of this variable can be ignored for a small module. If no value is specified, the smaller value is used instead. JULIA_CPU_THREADS or the value of half the number of logical processor cores.

JULIA_IMAGE_TIMINGS

A boolean value that determines whether detailed time information will be displayed during image compilation. The default value is 0.

JULIA_EXCLUSIVE

If a value other than 0 is set, Julia’s thread policy is consistent with thread execution on a dedicated computer: the main thread is located in the proc 0 subsystem, and threads are grouped by similarity. Otherwise, Julia transfers control of the thread policy to the operating system.

Formatting the REPL

Environment variables that determine how the REPL output should be formatted in the terminal. As a rule, the values of these variables should be set https://en.wikipedia.org/wiki/ANSI_escape_code [ANSI escape sequences]. Julia provides a high-level interface with most of the same functionality. See the section in the chapter Julia REPL.

JULIA_ERROR_COLOR

Formatting Base.error_color()' (default: light red, `"\033[91m") applied to errors in the terminal.

JULIA_WARN_COLOR

Formatting Base.warn_color()' (default: yellow, `"\033[93m") applied to warnings in the terminal.

JULIA_INFO_COLOR

Formatting Base.info_color()' (default: turquoise, `"\033[36m") applied to information messages in the terminal.

JULIA_INPUT_COLOR

Formatting Base.input_color()' (default: normal state, `"\033[0m") applied to input data in the terminal.

JULIA_ANSWER_COLOR

Formatting Base.answer_color()' (default: normal state, `"\033[0m") applied to terminal output.

Assembling the system image and package

JULIA_CPU_TARGET

Modifies the architecture of the target computer for (pre-) compilation system images and packages. 'JULIA_CPU_TARGET` only affects the generation of a machine code image output to the disk cache. Unlike --cpu-target or -C, command line parameter, it does not affect JIT code generation within the Julia session, where the machine code is stored only in memory.

Acceptable values for JULIA_CPU_TARGET can be obtained by running the command `julia -C help'.

Installation `JULIA_CPU_TARGET' is of great importance for heterogeneous computing systems, which may contain processors of different types and with different characteristics. This is common in high-performance computing (HPC) clusters, as component nodes may use different processors.

The processor’s target string is a list of strings separated by ;. Each line begins with the name of the processor or architecture, followed by an optional list of characteristics separated by ,. The generic or empty processor name means the basic required set of functions of the target ISA architecture, which is at least the architecture with which the C/C runtime is compiled.++. Each line is interpreted using LLVM.

Several special options are supported.

  1. clone_all

    It is used to force cloning of all functions in sysimg in the target object. When using the negative form (i.e. `-clone_all'), it disables full cloning, which is enabled by default for certain targets.

  2. base([0-9]*)

    Sets the index (based on 0) of the base target object. The base target object is the target object that is the basis of the current target object, i.e. functions that are not cloned will use the version in the base target object. This option allows you to force a full clone of the base target object (as if clone_all was specified for it) if it is not the default target (0). The index can only be smaller than the current index.

  3. opt_size

    Size optimization with minimal impact on performance. Clang/GCC -Os.

  4. min_size

    Optimizing only the size. Clang -Oz.

Debugging and profiling

JULIA_DEBUG

Enables debugging logging for a file or module. Additional information: Logging.

JULIA_PROFILE_PEEK_HEAP_SNAPSHOT

Enables the collection of a snapshot of the heap at runtime using the peek profiling mechanism. See the section Activation in progress.

JULIA_TIMING_SUBSYSTEMS

Allows you to enable or disable zones for a specific Julia launch. For example, when setting a variable value to +GC,-INFERENCE', the `GC zones will be enabled and the INFERENCE zones will be disabled. See the section Dynamic activation and deactivation of zones.

JULIA_GC_ALLOC_POOL

JULIA_GC_ALLOC_OTHER

JULIA_GC_ALLOC_PRINT

If these environment variables are set, they accept strings that may not necessarily start with a character. , followed by string interpolation of a colon-separated list of three 64-bit signed integers ('int64_t`). This triple of integers is a:b:c is an arithmetic sequence of a, a + b, a + 2*b …​ c.

  • If jl_gc_pool_alloc() is called for the nth time and `n belongs to the arithmetic sequence represented by $JULIA_GC_ALLOC_POOL, garbage collection is forced.

  • If maybe_collect() is called for the nth time and `n belongs to the arithmetic sequence represented by $JULIA_GC_ALLOC_OTHER, garbage collection is forced.

  • If 'jl_gc_collect()` is called for the nth time and `n belongs to the arithmetic sequence represented by $JULIA_GC_ALLOC_PRINT, the values of the number of calls to jl_gc_pool_alloc() and maybe_collect() are output.

If the value of the environment variable starts with the character the interval between garbage collection events is arbitrary.

These environment variables only work if the Julia code has been compiled with garbage collection debugging (i.e. if WITH_GC_DEBUG_ENV has the value 1 in the build configuration).

JULIA_GC_NO_GENERATIONAL

If a value other than 0 is set, the Julia garbage collector never performs a "fast cleanup" of memory.

This environment variable only works if the Julia code has been compiled with garbage collection debugging (i.e. if WITH_GC_DEBUG_ENV has the value 1 in the build configuration).

JULIA_GC_WAIT_FOR_DEBUGGER

If a value other than 0 is set, the Julia garbage collector will wait for the debugger to connect instead of interrupting it when a critical error occurs.

This environment variable only works if the Julia code has been compiled with garbage collection debugging (i.e. if WITH_GC_DEBUG_ENV has the value 1 in the build configuration).

ENABLE_JITPROFILING

If a value other than 0 is set, the compiler will create and register an event listener for JIT profiling.

This environment variable only works if the Julia code has been compiled with support for JIT profiling using either

ENABLE_GDBLISTENER

If a value other than 0 is set, it enables GDB registration of Julia code in release builds. Registration is always enabled in Julia debugging builds. It is recommended to use with `-g 2'.

JULIA_LLVM_ARGS

Arguments passed to the LLVM backend.

JULIA_FALLBACK_REPL

It forces the use of backup repl instead of REPL.jl.