Custom Julia system image

New in version 0.4.

If you use standard julia program, the basic functionalities and standard libraries of Julia are loaded from so called system image file which contains the machine code compiled from the Julia code. The Julia runtime can be configured to use a customized system image which may contain non-standard packages. This is a very effective way to reduce startup time of complex Julia packages such as PyCall. Furthermore, it can be used to workaround the problem in statically linked Python executable if you have the problem described in Your Python interpreter is statically linked to libpython.

How to use a custom system image

To compile a custom system image for PyJulia, run

$ python3 -m julia.sysimage

where sys.dll and sys.dylib may be used instead of in Windows and macOS, respectively.

The command line interface julia.sysimage will:

  • Install packages required for compiling the system image in an isolated Julia environment.
  • Install PyCall to be compiled into the system image in an isolated Julia environment.
  • Create the system image at the given path (./ in the above example).

To use this system image with PyJulia, you need to specify its path using sysimage keyword argument of the Julia constructor. For example, if you run python3 REPL at the directory where you ran the above julia.sysimage command, you can do

>>> from julia import Julia
>>> jl = Julia(sysimage="")

to initialize PyJulia. To check that this Julia runtime is using the correct system image, look at the output of Base.julia_cmd()

>>> from julia import Base
>>> Base.julia_cmd()
<PyCall.jlwrap `/PATH/TO/bin/julia-py -Cnative -J/PATH/TO/ -g1`>


  • PyCall and its dependencies cannot be updated after the system image is created. A new system image has to be created to update those packages.
  • The system image generated by julia.sysimage uses a different set of precompilation cache paths for each pair of julia-py executable and the system image file. Precompiled cache files generated by julia or a different julia-py executable cannot be reused by PyJulia when using the system image generated by julia.sysimage.
  • The absolute path of julia-py is embedded in the system image. This system image is not usable if julia-py is removed.

Command line interfaces

python3 -m julia.sysimage

Build system image.


python3 -m julia.sysimage

Generated system image can be passed to sysimage option of julia.api.Julia.


This script is not tested on Windows.


Launch Julia through PyJulia.

Currently, julia-py is primary used internally for supporting julia.sysimage command line interface. Using julia-py like normal Julia program requires --sysimage to be set to the system image created by julia.sysimage.


$ python3 -m julia.sysimage
$ julia-py --sysimage