Julia — User Guide

Julia is a high-level, high-performance dynamic programming language for technical computing. It pairs the interactive feel of a scripting language with the speed of a compiled one: you write expressive, dynamically-typed code, and a sophisticated just-in-time (JIT) compiler built on LLVM turns it into fast native machine code. Julia is organized around multiple dispatch — functions are defined by overloading them for different combinations of argument types — which makes it natural to write generic, composable, fast numerical code.

This guide shows you how to install Julia, run it, and use the julia command-line program and its interactive REPL in everyday work. It is written for people who want to use Julia. If you are building Julia from source, deploying it, embedding libjulia in another application, or studying its internals, see the companion Admin Guide.

Note

This guide documents the julia executable and its command-line interface as defined in the Julia source tree (version 1.14.0-DEV). The language itself — syntax, the standard library, and the package ecosystem — is vast; this guide focuses on launching and driving julia, with pointers into the official manual for deeper language topics.

Table of Contents

1. Quick Start
2. Installation
3. Running Julia
4. The Julia REPL
5. Everyday Tasks
6. Command-Line Options Reference
7. Environment Variables Reference
8. Projects, Packages, and the Depot
9. Performance, Threads, and Parallelism
10. How Julia Works (Concepts)
11. Troubleshooting
12. Frequently Asked Questions
13. Reference Tables

1. Quick Start

The fastest path from nothing to a working Julia prompt:

macOS / Linux

curl -fsSL https://install.julialang.org | sh

Windows

winget install --name Julia --id 9NJNWW8PVKMN -e -s msstore

This installs Juliaup, the official Julia version manager, which downloads the latest stable julia and keeps it up to date. Once installed, open a new terminal and start an interactive session:

julia

               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.14.0-DEV
 _/ |\__'_|_|_|\__'_|  |
|__/                   |

julia> 1 + 2
3

julia> ans
3

The julia> prompt is a REPL (read-eval-print loop). Type an expression, press Enter, and Julia evaluates it and shows the result. The special variable ans always holds the value of the last evaluated expression.

To exit, type exit() or press Ctrl+D.

To run a script non-interactively:

julia script.jl

Tip

A trailing semicolon suppresses the display of a result: julia> x = 1:1000; evaluates the expression and assigns x, but does not print the (potentially huge) value.

2. Installation

There are many ways to install Julia. The recommended method on every supported platform is Juliaup, the official installer and version multiplexer. It installs a fully functional Julia, lets you run several Julia versions side by side, and can keep them updated.

Important

Although some operating-system package managers ship a julia package, those installations are neither maintained nor endorsed by the Julia project. They may be outdated, broken, or unmaintained. Use the official binaries (via Juliaup) instead.

2.1 Windows

Install directly from the Microsoft Store, or run the equivalent command in any shell:

winget install --name Julia --id 9NJNWW8PVKMN -e -s msstore

Tip

On Windows, run Julia inside a modern terminal such as Windows Terminal for correct Unicode display and a better REPL experience.

Alternative Windows methods (use only if the Store is blocked):

• App Installer (MSIX): download https://install.julialang.org/Julia.appinstaller and double-click it, or run:

  Add-AppxPackage -AppInstallerFile https://install.julialang.org/Julia.appinstaller
  

• MSI installer: 64-bit from https://install.julialang.org/Julia-x64.msi, 32-bit from https://install.julialang.org/Julia-x86.msi. A per-user install needs no elevation; for a system-wide install run:

  msiexec /i <PATH_TO_JULIA_MSI> ALLUSERS=1
  

Warning

The MSI method has serious limitations and is generally not recommended — notably, there is no automatic update mechanism for Juliaup with this method.

2.2 macOS and Linux

Run the official installer script:

curl -fsSL https://install.julialang.org | sh

You can pass arguments to the installer using the -s -- separator:

curl -fsSL https://install.julialang.org | sh -s -- <ARGS>

Other package managers (each installs juliaup, not just a bare julia):

Homebrew (macOS/Linux)

brew install juliaup

Arch Linux (AUR)

# Juliaup is available in the Arch User Repository
# e.g. with an AUR helper:
yay -S juliaup

openSUSE Tumbleweed

sudo zypper install juliaup

cargo (cross-platform)

cargo install juliaup

2.3 Verifying the installation

julia --version

julia version 1.14.0-DEV

If everything works, running julia with no arguments shows the banner and an interactive prompt. You can read the getting-started chapter of the manual for next steps.

2.4 Uninstalling Julia

By default, Julia installs nothing outside its own install directory and ~/.julia. Julia and the vast majority of Julia packages can be completely removed by deleting:

• the Julia/Juliaup install directory (default ~/.juliaup), and
• the user depot ~/.julia.

3. Running Julia

The general form of the command line is:

julia [switches] -- [programfile] [args...]

Anything after the program file (or after the -- delimiter) is passed to your program; anything before is interpreted by Julia. There are four broad ways to run Julia code.

3.1 Interactive session (REPL)

julia

Starts the REPL. This is the default when no program file or evaluation flag is given and the input is a terminal. See Section 4.

3.2 Running a script file

julia script.jl

julia script.jl arg1 arg2

Additional arguments are available to your script in the global constant ARGS, and the script's own path is in PROGRAM_FILE:

# script.jl
println(PROGRAM_FILE)
for x in ARGS
    println(x)
end

julia script.jl foo bar

script.jl
foo
bar

Use -- to keep Julia's own switches separate from your script's arguments:

julia --color=yes -O -- script.jl arg1 arg2

3.3 Evaluating an expression directly

julia -e 'println("Hello, world!")'

Hello, world!

-E (--print) evaluates and displays the result:

julia -E '2 ^ 10'

1024

Note

ARGS is also populated when you use -e, but PROGRAM_FILE will be empty in that case.

3.4 The Main.main entry point (@main)

As of Julia 1.11, defining a main function with the exported @main macro causes Julia to run Main.main(Base.ARGS) automatically after a script or expression finishes:

# hello.jl
(@main)(args) = println("Hello $(args[1])!")

julia hello.jl Buddy

Hello Buddy!

The return value of (@main) determines the process exit code: nothing yields exit code 0, or a value convertible to a Cint is used directly (typically in the range 0:255).

julia -e "(@main)(args) = 1"; echo $?

1

Important

Only the main binding in the Main module triggers this behavior, and only if the @main macro was used in the defining module. A plain main(args) = ... definition will not run automatically. The opt-in can also happen after definition: main(args) = ...; @main.

Tip

For compatibility with Julia versions before 1.11, end scripts with:

@static @isdefined(var"@main") ? (@main) : exit(main(ARGS))

3.5 Running a package's entry point with -m

julia -m SomePackage arg1 arg2

Runs the @main entry point of SomePackage with the given arguments.

4. The Julia REPL

The REPL is one of Julia's most powerful tools. Besides plain evaluation, it has several modes you switch into by typing a single character at an empty julia> prompt.

4.1 Help mode

Press ? at an empty prompt, then type the name of anything you want documented:

help?> begin
search: begin disable_sigint reenable_sigint

  begin

  begin...end denotes a block of code.

Help mode works for keywords, functions, types, and most objects you encounter — it's a built-in learning resource.

4.2 Package mode

Press ] to enter the package manager. The prompt changes to show the active environment, e.g. (@v1.14) pkg>. Type ? here for Pkg-specific help. See Section 8.

4.3 Shell mode

Press ; to run a single command in the system shell:

shell> ls

Note

The shell used is controlled by JULIA_SHELL (defaults to $SHELL, then /bin/sh). On Windows this is ignored and external commands run directly.

4.4 ans and including files

• ans holds the value of the last evaluated expression (interactive sessions only).
• include("file.jl") evaluates the contents of a source file in the current session — handy for loading code you're editing without restarting.

4.5 Customizing REPL colors

REPL output colors can be tuned with environment variables (ANSI escape sequences). See Section 7 for JULIA_ERROR_COLOR, JULIA_WARN_COLOR, JULIA_INFO_COLOR, JULIA_INPUT_COLOR, JULIA_ANSWER_COLOR, and the standard NO_COLOR / FORCE_COLOR variables.

5. Everyday Tasks

This section collects common things you'll want to do, as copy-pasteable recipes.

5.1 Run a one-liner and print the result

julia -E 'sum(1:100)'

5050

5.2 Read script arguments

# greet.jl
name = isempty(ARGS) ? "world" : ARGS[1]
println("Hello, $name!")

julia greet.jl Ada

Hello, Ada!

5.3 Make a script return a specific exit code

# check.jl
(@main)(args) = isempty(args) ? 2 : 0

julia check.jl; echo "exit=$?"

exit=2

5.4 Run startup code automatically

Put code you want run every time Julia starts in ~/.julia/config/startup.jl:

echo 'println("Greetings!")' > ~/.julia/config/startup.jl
julia

Greetings!
...

Note

You may need to create the ~/.julia/config/ directory the first time. If JULIA_DEPOT_PATH is set, the startup file lives at $JULIA_DEPOT_PATH/config/startup.jl instead.

To run startup code only in interactive sessions (not for scripts), use atreplinit inside startup.jl:

atreplinit() do repl
    # interactive-only setup here
end

5.5 Run without loading the startup file

Useful for reproducible runs and CI:

julia --startup-file=no script.jl

5.6 Start Julia with more threads

julia -t auto

julia --threads=4

See Section 9.

5.7 Run a faster-to-compile, lower-optimization session

For quick exploratory work where startup latency matters more than peak speed:

julia -O1

For maximum runtime performance:

julia -O3

5.8 Suppress the banner for clean output

julia -q

julia --banner=no

5.9 Turn deprecation warnings into errors (catch them early in tests)

julia --depwarn=error runtests.jl

5.10 Measure where time and memory go

julia --track-allocation=user script.jl

julia --code-coverage=user script.jl

These write .mem / coverage data alongside your source files. See Section 9 and the Profile chapter.

6. Command-Line Options Reference

This is the complete list of switches accepted by the julia executable. A * marks the default value where one applies; options marked ($) may trigger package precompilation.

Note

Options of the form --option={...} may be written as --option=value or --option value (e.g. julia --banner=no ≡ julia --banner no). Options of the form --option[=...] can only be written as --option=value or bare --option, never as --option value.

6.1 Version, help, and startup

6.2 Projects and code loading

6.3 Evaluating code

6.4 Threads and parallelism

6.5 Code generation and optimization

6.6 Warnings

6.7 Memory and garbage collection

6.8 Profiling and tracing

6.9 System-image / static-output generation

These are mostly for advanced and build/deploy use; see the Admin Guide.

7. Environment Variables Reference

Julia reads many environment variables, most prefixed JULIA. You can set them in the usual OS way, or — for variables that take effect at runtime — from within Julia via ENV["JULIA_EDITOR"] = "vim", or permanently in startup.jl.

Important

Several variables must be set before Julia starts; setting them in startup.jl is too late. These include JULIA_NUM_THREADS, JULIA_PROJECT, and JULIA_DEPOT_PATH. The notes below flag them.

Caution

Avoid changing environment variables during runtime. Beyond timing problems, mutating ENV while code runs can introduce data races into otherwise benign code.

Tip

Run versioninfo(verbose=true) (from InteractiveUtils) to list all Julia-relevant environment variables currently defined.

File locations

Package manager (Pkg.jl)

Network transport

External applications

Parallelization

Garbage collection

REPL formatting

System- and package-image building

Debugging and profiling

8. Projects, Packages, and the Depot

Julia manages dependencies with environments (projects) and a built-in package manager, Pkg. This section covers the day-to-day mechanics; the full Pkg documentation lives at pkgdocs.julialang.org.

8.1 Key concepts

Project / environment : A directory containing a Project.toml (your dependencies) and usually a Manifest.toml (the exact resolved versions). The active project determines what import/using can load.

Depot : The directory tree (default ~/.julia) where Pkg stores registries, downloaded packages, compiled caches, configuration, and REPL history. Controlled by JULIA_DEPOT_PATH.

Load path : The ordered list (LOAD_PATH, default ["@", "@v#.#", "@stdlib"]) Julia searches when resolving import. Controlled by JULIA_LOAD_PATH.

8.2 Selecting the active project

# Use the current directory's project (searching parents for Project.toml)
julia --project=@.

# Use a specific project directory
julia --project=/path/to/MyProject

# Use a throwaway temporary environment
julia --project=@temp

Equivalently, set JULIA_PROJECT before launch (note: --project takes precedence).

8.3 Managing packages in the REPL

Press ] to enter Pkg mode:

(@v1.14) pkg> add Example
(@v1.14) pkg> status
(@v1.14) pkg> update
(@v1.14) pkg> rm Example

Press Backspace at an empty Pkg prompt to return to the julia> prompt.

Tip

For a fresh, isolated environment for a piece of work:

mkdir myanalysis && cd myanalysis
julia --project=.

then ]add the packages you need. The resulting Project.toml/Manifest.toml make the environment reproducible.

8.4 Precompilation and image caching

• Incremental precompilation (--compiled-modules) caches the parsed/lowered form of packages so they load faster.
• Package images / pkgimages (--pkgimages) additionally cache native code.

Both default to yes. The existing value lets you use caches without creating new ones — useful on read-only or shared filesystems.

Note

Options marked ($) in Section 6 (such as -O, -g, --check-bounds) can change the generated code and therefore may trigger a round of package precompilation when you change them.

9. Performance, Threads, and Parallelism

Julia offers several layers of parallelism. This section shows how to enable each from the command line; the conceptual chapters in the manual (Multi-Threading, Distributed Computing) go deeper.

9.1 Threads (shared memory)

# Let Julia pick a sensible default
julia -t auto

# 4 threads in the default pool, 2 in the interactive pool
julia -t 4,2

Or via the environment (must be set before startup):

export JULIA_NUM_THREADS=4
julia

Julia has two threadpools: :default (for compute) and :interactive (kept responsive for UI/REPL work). The N,M syntax sizes them separately.

9.2 Garbage-collection threads

julia --gcthreads=4,1

N threads run the GC mark phase; M (0 or 1) runs concurrent sweeping.

9.3 Worker processes (distributed memory)

# 4 extra local workers
julia -p 4

# One worker per local CPU thread
julia -p auto

# Workers on remote hosts listed in a file
julia --machine-file hosts.txt

Each line of the machine file has the form [count*][user@]host[:port] [bind_addr[:port]]. Remote hosts must be reachable over password-less ssh, with Julia installed at the same path as on the host.

9.4 Controlling memory pressure

julia --heap-size-hint=4G

Forces garbage collection once memory usage exceeds the hint. Accepts byte counts with units (KB/MB/GB/TB) or a percentage of physical memory (--heap-size-hint=50%). The environment variable JULIA_HEAP_SIZE_HINT does the same.

9.5 Optimization levels and latency trade-offs

Tip

There is an inherent trade-off between time-to-first-result (compilation latency) and steady-state speed. For short-lived scripts, lower optimization can finish sooner overall; for long-running compute, -O3 pays off.

9.6 CPU targeting

# See available CPU targets
julia -C help

Use -C/--cpu-target to constrain which CPU features the JIT may use. For cached images, set JULIA_CPU_TARGET instead — important on heterogeneous HPC clusters where nodes have different processors.

10. How Julia Works (Concepts)

You don't need this section to use Julia, but it explains why the command-line options behave the way they do.

10.1 The startup pipeline

The julia you run is a small loader. It locates and opens the Julia runtime libraries (in order: a probed/ bundled libstdc++, then libjulia-internal, then optionally libjulia-codegen), wires up their exported functions, initializes options, and jumps into the runtime's REPL entry point. The compiler library (libjulia-codegen) is optional: if it's absent, the runtime falls back to a built-in implementation that can run already-compiled code but not generate new code.

  julia (loader)
      │  dlopen, in order:
      ├── libstdc++        (system one if newer, else bundled)
      ├── libjulia-internal
      └── libjulia-codegen (optional → fallback to internal)
      │
      ▼
  jl_repl_entrypoint  →  REPL / script / -e expression

Note

This is why --sysimage, --compile, and --pkgimages exist: most of "starting Julia fast" is about not recompiling code that has already been compiled and cached in the system image or package images.

10.2 Just-in-time compilation

Julia is dynamically typed but compiled. The first time a function is called with a particular combination of argument types, the compiler specializes and compiles it to native code via LLVM; subsequent calls reuse that code. This is the source of the famous "time-to-first-X" latency — and why caching (sysimage, pkgimages, precompilation) matters so much.

10.3 Multiple dispatch

Julia chooses which method of a function to run based on the types of all its arguments, not just the first. This is the organizing principle of the language and the reason generic code (written once) can be fast and composable across many types.

10.4 The system image

A system image (.ji / shared library) is a snapshot of a compiled Julia session — Base, the standard library, and their compiled methods. Julia starts from one by default (-J/--sysimage). You can generate custom images (--output-ji, --output-o) or trimmed ones (--trim) to speed up startup or ship smaller binaries; see the Admin Guide.

10.5 Source organization (for the curious)

11. Troubleshooting

Format: the symptom, the likely cause, the fix, and how to avoid it next time.

Error: julia: command not found

• Cause: Julia's bin directory is not on your PATH (common with the MSI installer or a manual install).
• Solution: Reinstall via Juliaup with --add-to-path=yes, or add the install directory (default ~/.juliaup/bin) to PATH and open a new terminal.
• Prevention: Prefer the Juliaup-based install, which configures PATH for you.

Problem: Julia feels slow the first time I call a function

• Cause: Just-in-time compilation. The first call with a given set of argument types is compiled; later calls are fast. This is normal, especially right after startup ("time-to-first-plot").
• Solution: Keep a long-running session rather than relaunching for each task; let packages precompile (--compiled-modules=yes, the default); for scripts, consider building a custom system image.
• Prevention: Don't benchmark the first call. Warm up the function once, then measure.

Problem: Startup is slow, or it recompiles packages every time

• Cause: Precompilation caches are being created repeatedly — often because optimization-affecting flags (-O, -g, --check-bounds) change between runs, or because the depot is on a read-only/changing filesystem.
• Solution: Keep the same flags between runs; if the depot is read-only, use --compiled-modules=existing and --pkgimages=existing.
• Prevention: Pin a consistent launch command (e.g. in a wrapper script or your editor's Julia settings).

Problem: My script's arguments are being eaten by Julia

• Cause: Switches after the program file, or argument names that collide with Julia switches, are being parsed by Julia.
• Solution: Put -- before the program file: julia [switches] -- script.jl arg1 arg2.
• Prevention: Always separate Julia options from script options with --.

Problem: JULIA_NUM_THREADS (or JULIA_PROJECT) seems to be ignored

• Cause: It was set after Julia started — for example, inside startup.jl.
• Solution: Set it in your shell before launching julia, e.g. export JULIA_NUM_THREADS=8, or use the -t/--project switch.
• Prevention: Treat JULIA_NUM_THREADS, JULIA_PROJECT, and JULIA_DEPOT_PATH as pre-launch settings.

Problem: REPL output has no color (or unwanted color)

• Cause: NO_COLOR/FORCE_COLOR is set, or the terminal isn't detected as color-capable.
• Solution: Force it explicitly: julia --color=yes (or --color=no). --color overrides NO_COLOR/FORCE_COLOR.
• Prevention: Set --color in your launch command for predictable output in pipelines and CI.

Problem: Forgetting an argument to --trace-compile overwrites a file

• Cause: --trace-compile takes a value as the next token, so julia --trace-compile script.jl treats script.jl as the output target.
• Solution: Use the = form: julia --trace-compile=stderr script.jl.
• Prevention: For value-taking switches, always use --option=value.

Problem: Deprecation warnings are noisy / I want to catch them in tests

• Cause: Default --depwarn=no (warnings off) or yes (warnings shown).
• Solution: Run tests with --depwarn=error to turn deprecations into hard failures.
• Prevention: Add --depwarn=error to your test runner command.

Problem: Windows + PowerShell hangs after an external command fails

• Cause: A known interaction (community issue #59931) where Julia can hang after a run of an external command fails in some Windows/PowerShell environments.
• Solution: Run inside Windows Terminal; update to the latest Julia; check the issue tracker for the current status.
• Prevention: Use the recommended modern terminal on Windows and keep Julia current via Juliaup.

Problem: A package fails to download / hash verification errors on a network filesystem

• Cause: Artifact hashes can mismatch when moving files across different filesystem types.
• Solution: As a last resort, set JULIA_PKG_IGNORE_HASHES=1 (Julia 1.6+) — but understand this disables download verification.
• Prevention: Keep the depot on a single, consistent filesystem.

Problem: I'm behind a restrictive firewall and package installs fail

• Cause: The default eager-style fetching or PkgServer protocol is blocked.
• Solution: Use JULIA_PKG_SERVER_REGISTRY_PREFERENCE=conservative (the default), or set JULIA_PKG_SERVER="" to fetch directly from hosts; enable JULIA_PKG_OFFLINE=true to work entirely offline.
• Prevention: Configure these in your environment for locked-down networks.

Problem: I need to file a good bug report

• Solution: Run julia --bug-report=KIND (see julia --bug-report=help). It uses BugReporting.jl to capture a reproducible session. Report at https://github.com/JuliaLang/julia/issues.

12. Frequently Asked Questions

Q: What is Julia, in one sentence? A high-level, high-performance dynamic language for technical computing that combines an interactive, scripting-like workflow with the speed of a compiled language, organized around multiple dispatch.

Q: How should I install Julia? Use Juliaup, the official installer/version manager: curl -fsSL https://install.julialang.org | sh on macOS/Linux, or winget install --name Julia --id 9NJNWW8PVKMN -e -s msstore on Windows. Avoid OS-package-manager julia packages, which the project does not endorse.

Q: How do I run several Julia versions at once? That's exactly what Juliaup is for. It lets you install and switch between channels (e.g. lts, release) and run different versions simultaneously.

Q: How do I run a .jl file? julia script.jl. Pass arguments after it (julia script.jl a b), or use -- to be unambiguous (julia -- script.jl a b). Arguments arrive in the global ARGS.

Q: How do I evaluate a quick expression without writing a file? julia -e 'expr' to run it, or julia -E 'expr' to run and print the result.

Q: What's @main? A macro (Julia 1.11+) that opts a Main.main(args) function into being run automatically when a script/expression finishes, with its return value becoming the process exit code. Useful for writing CLI applications.

Q: How do I start Julia with multiple threads? julia -t auto or julia -t N (or set JULIA_NUM_THREADS before launch). Use julia -t N,M to size the :default and :interactive threadpools separately.

Q: Threads vs. processes — which do I want? Threads (-t) share memory within one process; processes (-p/--machine-file) are separate workers (possibly on other machines) and are used for distributed computing. Use threads for shared-memory parallelism, processes to scale across nodes.

Q: Why is Julia slow the first time and fast afterward? Just-in-time compilation. Code is compiled on first use per argument-type combination, then cached. Keep a session alive, and rely on precompilation and package images to reduce this latency.

Q: How do I make a fresh, reproducible environment for a project? Create a directory, start Julia with --project=., and ]add your packages. The generated Project.toml/Manifest.toml pin everything.

Q: How do I run code automatically at every startup? Put it in ~/.julia/config/startup.jl (or $JULIA_DEPOT_PATH/config/startup.jl). For interactive-only setup, wrap it in atreplinit(...).

Q: How do I disable the startup banner and warnings? julia -q, or julia --banner=no.

Q: How do I look up documentation without leaving the REPL? Press ? at the prompt to enter help mode, then type the name you want documented.

Q: How do I manage packages without leaving the REPL? Press ] to enter Pkg mode (add, rm, status, update, …), then Backspace to leave it.

Q: Where does Julia store packages and caches? In the depot, default ~/.julia, configurable via JULIA_DEPOT_PATH. Uninstalling Julia is as simple as deleting the install directory and the depot.

Q: How do I limit memory usage? julia --heap-size-hint=4G (or =50%), which forces GC above the given threshold. Equivalent env var: JULIA_HEAP_SIZE_HINT.

Q: How do I turn off colored output for logs/CI? julia --color=no. The --color switch overrides the NO_COLOR/FORCE_COLOR environment variables.

Q: Is Julia free / open source? Yes — Julia is open source under the MIT license.

Q: Where do I learn the language itself? The official manual at https://docs.julialang.org, the learning resources at https://julialang.org/learning/, the Discourse forum, and community Zulip/Slack. The REPL's help mode (?) is a great built-in reference.

13. Reference Tables

13.1 REPL modes

13.2 Exiting Julia

13.3 Most-used launch commands

13.4 Globals available to your code

13.5 Where to go next