Modules in Julia are separate variable workspaces, i.e. they introduce
a new global scope. They are delimited syntactically, inside
moduleName...end. Modules allow you to create top-level definitions (aka
global variables) without worrying about name conflicts when your code
is used together with somebody else’s. Within a module, you can
control which names from other modules are visible (via importing),
and specify which of your names are intended to be public (via
The following example demonstrates the major features of modules. It is not meant to be run, but is shown for illustrative purposes:
moduleMyModuleusingLibusingBigLib:thing1,thing2importBase.showimportallOtherLibexportMyType,footype MyTypexendbar(x)=2xfoo(a::MyType)=bar(a.x)+1show(io,a::MyType)=print(io,"MyType $(a.x)")end
Note that the style is not to indent the body of the module, since that would typically lead to whole files being indented.
This module defines a type
MyType, and two functions. Function
foo and type
MyType are exported, and so will be available for
importing into other modules. Function
bar is private to
usingLib means that a module called
Lib will be
available for resolving names as needed. When a global variable is
encountered that has no definition in the current module, the system
will search for it among variables exported by
Lib and import it if
it is found there.
This means that all uses of that global within the current module will
resolve to the definition of that variable in
usingBigLib:thing1,thing2 is a syntactic shortcut for
import keyword supports all the same syntax as
using, but only
operates on a single name at a time. It does not add modules to be searched
import also differs from
using in that
functions must be imported using
import to be extended with new methods.
MyModule above we wanted to add a method to the standard
function, so we had to write
Functions whose names are only visible via
using cannot be extended.
importall explicitly imports all names exported by the
specified module, as if
import were individually used on all of them.
Once a variable is made visible via
import, a module may
not create its own variable with the same name.
Imported variables are read-only; assigning to a global variable always
affects a variable owned by the current module, or else raises an error.
Summary of module usage¶
To load a module, two main keywords can be used:
import. To understand their differences, consider the following example:
In this module we export the
y functions (with the keyword
export), and also have the non-exported function
p. There are several different ways to load the Module and its inner functions into the current workspace:
|Import Command||What is brought into scope||Available for method extension|
Modules and files¶
Files and file names are mostly unrelated to modules; modules are associated only with module expressions. One can have multiple files per module, and multiple modules per file:
Including the same code in different modules provides mixin-like behavior. One could use this to run the same code with different base definitions, for example testing code by running it with “safe” versions of some operators:
There are three important standard modules: Main, Core, and Base.
Main is the top-level module, and Julia starts with Main set as the
current module. Variables defined at the prompt go in Main, and
whos() lists variables in Main.
Core contains all identifiers considered “built in” to the language, i.e.
part of the core language and not libraries. Every module implicitly
usingCore, since you can’t do anything without those
Base is the standard library (the contents of base/). All modules implicitly
usingBase, since this is needed in the vast majority of cases.
Default top-level definitions and bare modules¶
In addition to
usingBase, modules also perform
default, to facilitate adding constructors to new types.
A new module also automatically contains a definition of the
which evaluates expressions within the context of that module.
If these default definitions are not wanted, modules can be defined using the
baremodule instead (note:
Core is still imported, as per above).
In terms of
baremodule, a standard
module looks like this:
Relative and absolute module paths¶
Given the statement
usingFoo, the system looks for
Main. If the module does not exist, the system
require("Foo"), which typically results in loading
code from an installed package.
However, some modules contain submodules, which means you sometimes
need to access a module that is not directly available in
There are two ways to do this. The first is to use an absolute path,
usingBase.Sort. The second is to use a relative path,
which makes it easier to import submodules of the current module or
any of its enclosing modules:
Parent contains a submodule
Utils, and code in
Parent wants the contents of
Utils to be visible. This is
done by starting the
using path with a period. Adding more leading
periods moves up additional levels in the module hierarchy. For example
using..Utils would look for
module rather than in
Note that relative-import qualifiers are only valid in
Module file paths¶
The global variable LOAD_PATH contains the directories Julia searches for
modules when calling
require. It can be extended using
Putting this statement in the file
~/.juliarc.jl will extend LOAD_PATH
on every Julia startup. Alternatively, the module load path can be
extended by defining the environment variable JULIA_LOAD_PATH.
If a name is qualified (e.g.
Base.sin), then it can be accessed even if
it is not exported. This is often useful when debugging.
Macro names are written with
@ in import and export statements, e.g.
importMod.@mac. Macros in other modules can be invoked as
M.x=y does not work to assign a global in another module;
global assignment is always module-local.
A variable can be “reserved” for the current module without assigning to
it by declaring it as
globalx at the top level. This can be used to
prevent name conflicts for globals initialized after load time.
Module initialization and precompilation¶
Large modules can take several second to load because executing all of the statements in a module often involves compiling a large amount of code. Julia provides the ability to create precompiled versions of modules to reduce this time.
There are two mechanisms that can achieve this: incremental compile and custom system image.
To create a custom system image that can be used when starting Julia with the
recompile Julia after modifying the file
base/userimg.jl to require the desired modules.
To create an incremental precompiled module file, add
__precompile__() at the top of your module file (before the
module starts). This will cause it to be automatically compiled
the first time it is imported. Alternatively, you can manually call
Base.compilecache(modulename). The resulting cache files will be
Base.LOAD_CACHE_PATH. Subsequently, the module is
automatically recompiled upon
import whenever any of its
dependencies change; dependencies are modules it imports, the Julia
build, files it includes, or explicit dependencies declared by
include_dependency(path) in the module file(s). Precompiling a
module also recursively precompiles any modules that are imported
therein. If you know that it is not safe to precompile your module
(for the reasons described below), you should put
__precompile__(false) in the module file to cause
throw an error (and thereby prevent the module from being imported by
any other precompiled module).
__precompile__() should not be used in a module unless all of its
dependencies are also using
__precompile__(). Failure to do so can result
in a runtime error when loading the module.
In order to make your module work with precompilation,
however, you may need to change your module to explicitly separate any
initialization steps that must occur at runtime from steps that can
occur at compile time. For this purpose, Julia allows you to define
__init__() function in your module that executes any
initialization steps that must occur at runtime.
This function will not be called during compilation
You may, of course, call it manually if necessary,
but the default is to assume this function deals with computing state for
the local machine, which does not need to be – or even should not be –
captured in the compiled image.
It will be called after the module is loaded into a process,
including if it is being loaded into an incremental compile
--output-incremental=yes), but not if it is being loaded
into a full-compilation process.
In particular, if you define a
function__init__() in a module,
then Julia will call
__init__() immediately after the module is
loaded (e.g., by
require) at runtime for
the first time (i.e.,
__init__ is only called once, and only
after all statements in the module have been executed). Because it is
called after the module is fully imported, any submodules or other
imported modules have their
__init__ functions called before the
__init__ of the enclosing module.
Two typical uses of
__init__ are calling runtime initialization
functions of external C libraries and initializing global constants
that involve pointers returned by external libraries. For example,
suppose that we are calling a C library
libfoo that requires us
to call a
foo_init() initialization function at runtime. Suppose
that we also want to define a global constant
holds the return value of a
void*foo_data() function defined by
libfoo — this constant must be initialized at runtime (not at compile
time) because the pointer address will change from run to run. You
could accomplish this by defining the following
in your module:
Notice that it is perfectly possible to define a global inside
a function like
__init__; this is one of the advantages of using a
Obviously, any other globals in your module that depends on
would also have to be initialized in
Constants involving most Julia objects that are not produced by
ccall do not need to be placed in
__init__: their definitions
can be precompiled and loaded from the cached module image.
This includes complicated heap-allocated objects like arrays.
However, any routine that returns a raw pointer value must be called
at runtime for precompilation to work
(Ptr objects will turn into null pointers unless they are hidden inside an isbits object).
This includes the return values of the Julia functions
Dictionary and set types, or in general anything that depends on the
output of a
hash(key) method, are a trickier case. In the common
case where the keys are numbers, strings, symbols, ranges,
or compositions of these types (via arrays, tuples, sets, pairs, etc.)
they are safe to precompile. However, for a few other key types, such
DataType and generic user-defined types where
you haven’t defined a
hash method, the fallback
depends on the memory address of the object (via its
and hence may change from run to run.
If you have one of these key types, or if you aren’t sure,
to be safe you can initialize this dictionary from within your
Alternatively, you can use the
ObjectIdDict dictionary type,
which is specially handled by precompilation so that it is safe to
initialize at compile-time.
When using precompilation, it is important to keep a clear sense of the distinction between the compilation phase and the execution phase. In this mode, it will often be much more clearly apparent that Julia is a compiler which allows execution of arbitrary Julia code, not a standalone interpreter that also generates compiled code.
Other known potential failure scenarios include:
Global counters (for example, for attempting to uniquely identify objects) Consider the following code snippet:
while the intent of this code was to give every instance a unique id, the counter value is recorded at the end of compilation. All subsequent usages of this incrementally compiled module will start from that same counter value.
object_id(which works by hashing the memory pointer) has similar issues (see notes on Dict usage below).
One alternative is to store both
current_module()and the current
countervalue, however, it may be better to redesign the code to not depend on this global state.
Associative collections (such as
Set) need to be re-hashed in
__init__. (In the future, a mechanism may be provided to register an initializer function.)
Depending on compile-time side-effects persisting through load-time. Example include: modifying arrays or other variables in other Julia modules; maintaining handles to open files or devices; storing pointers to other system resources (including memory);
Creating accidental “copies” of global state from another module, by referencing it directly instead of via its lookup path. For example, (in global scope):
#mystdout = Base.STDOUT #= will not work correctly, since this will copy Base.STDOUT into this module =## instead use accessor functions:getstdout()=Base.STDOUT#= best option =## or move the assignment into the runtime:__init__()=globalmystdout=Base.STDOUT#= also works =#
Several additional restrictions are placed on the operations that can be done while precompiling code to help the user avoid other wrong-behavior situations:
evalto cause a side-effect in another module. This will also cause a warning to be emitted when the incremental precompile flag is set.
globalconststatements from local scope after
__init__()has been started (see issue #12010 for plans to add an error for this)
- Replacing a module (or calling
workspace()) is a runtime error while doing an incremental precompile.
A few other points to be aware of:
- No code reload / cache invalidation is performed after changes are made to the source files themselves,
Pkg.update), and no cleanup is done after
- The memory sharing behavior of a reshaped array is disregarded by precompilation (each view gets its own copy)
- Expecting the filesystem to be unchanged between compile-time and runtime
source_path()to find resources at runtime, or the BinDeps
@checked_libmacro. Sometimes this is unavoidable. However, when possible, it can be good practice to copy resources into the module at compile-time so they won’t need to be found at runtime.
- WeakRef objects and finalizers are not currently handled properly by the serializer (this will be fixed in an upcoming release).