# 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](#1-quick-start)
2. [Installation](#2-installation)
3. [Running Julia](#3-running-julia)
4. [The Julia REPL](#4-the-julia-repl)
5. [Everyday Tasks](#5-everyday-tasks)
6. [Command-Line Options Reference](#6-command-line-options-reference)
7. [Environment Variables Reference](#7-environment-variables-reference)
8. [Projects, Packages, and the Depot](#8-projects-packages-and-the-depot)
9. [Performance, Threads, and Parallelism](#9-performance-threads-and-parallelism)
10. [How Julia Works (Concepts)](#10-how-julia-works-concepts)
11. [Troubleshooting](#11-troubleshooting)
12. [Frequently Asked Questions](#12-frequently-asked-questions)
13. [Reference Tables](#13-reference-tables)

---

## 1. Quick Start

The fastest path from nothing to a working Julia prompt:

=== "macOS / Linux"

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

=== "Windows"

    ```powershell
    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:

```bash
julia
```

```text
               _
   _       _ _(_)_     |  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 <kbd>Enter</kbd>, 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 <kbd>Ctrl</kbd>+<kbd>D</kbd>.

To run a script non-interactively:

```bash
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:

```powershell
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:
  ```powershell
  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:
  ```powershell
  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:

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

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

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

| Installer argument | Effect |
|---|---|
| `--yes` / `-y` | Non-interactive install; use defaults or supplied values |
| `--default-channel=<NAME>` | Set the default Juliaup channel (e.g. `lts`) |
| `--add-to-path=<yes\|no>` | Whether to add Julia to `PATH` (default `yes`) |
| `--background-selfupdate=<SECONDS>` | Create a CRON job to auto-update Juliaup (`0` = none) |
| `--startup-selfupdate=<MINUTES>` | How often Julia checks for new Juliaup versions (default `1440`) |
| `-p=<PATH>` / `--path` | Where to install Julia/Juliaup binaries (default `~/.juliaup`) |

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

=== "Homebrew (macOS/Linux)"

    ```bash
    brew install juliaup
    ```

=== "Arch Linux (AUR)"

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

=== "openSUSE Tumbleweed"

    ```bash
    sudo zypper install juliaup
    ```

=== "cargo (cross-platform)"

    ```bash
    cargo install juliaup
    ```

### 2.3 Verifying the installation

```bash
julia --version
```

```text
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](https://docs.julialang.org/en/v1/manual/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:

```text
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)

```bash
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](#4-the-julia-repl).

### 3.2 Running a script file

```bash
julia script.jl
```

```bash
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`:

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

```bash
julia script.jl foo bar
```

```text
script.jl
foo
bar
```

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

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

### 3.3 Evaluating an expression directly

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

```text
Hello, world!
```

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

```bash
julia -E '2 ^ 10'
```

```text
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:

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

```bash
julia hello.jl Buddy
```

```text
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`).

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

```text
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:
> ```julia
> @static @isdefined(var"@main") ? (@main) : exit(main(ARGS))
> ```

### 3.5 Running a package's entry point with `-m`

```bash
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.

| Key | Mode | Purpose |
|---|---|---|
| *(default)* | **Julian** | Evaluate Julia expressions |
| `?` | **Help** | Look up documentation for a keyword, function, type, or macro |
| `]` | **Pkg** | Manage packages and environments (`add`, `rm`, `status`, …) |
| `;` | **Shell** | Run a single OS shell command |

### 4.1 Help mode

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

```text
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](#8-projects-packages-and-the-depot).

### 4.3 Shell mode

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

```text
shell> ls
```

> [!NOTE]
> The shell used is controlled by [`JULIA_SHELL`](#7-environment-variables-reference) (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](#7-environment-variables-reference) 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

```bash
julia -E 'sum(1:100)'
```

```text
5050
```

### 5.2 Read script arguments

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

```bash
julia greet.jl Ada
```

```text
Hello, Ada!
```

### 5.3 Make a script return a specific exit code

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

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

```text
exit=2
```

### 5.4 Run startup code automatically

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

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

```text
Greetings!
...
```

> [!NOTE]
> You may need to create the `~/.julia/config/` directory the first time. If [`JULIA_DEPOT_PATH`](#7-environment-variables-reference) 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`:

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

### 5.5 Run without loading the startup file

Useful for reproducible runs and CI:

```bash
julia --startup-file=no script.jl
```

### 5.6 Start Julia with more threads

```bash
julia -t auto
```

```bash
julia --threads=4
```

See [Section 9](#9-performance-threads-and-parallelism).

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

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

```bash
julia -O1
```

For maximum runtime performance:

```bash
julia -O3
```

### 5.8 Suppress the banner for clean output

```bash
julia -q
```

```bash
julia --banner=no
```

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

```bash
julia --depwarn=error runtests.jl
```

### 5.10 Measure where time and memory go

```bash
julia --track-allocation=user script.jl
```

```bash
julia --code-coverage=user script.jl
```

These write `.mem` / coverage data alongside your source files. See [Section 9](#9-performance-threads-and-parallelism) and the [`Profile`](https://docs.julialang.org/en/v1/manual/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

| Switch | Description |
|---|---|
| `-v`, `--version` | Display version information |
| `-h`, `--help` | Print command-line options |
| `--help-hidden` | Print uncommon options not shown by `-h` |
| `-J`, `--sysimage <file>` | Start up with the given system image file |
| `-H`, `--home <dir>` | Set location of the `julia` executable |
| `--startup-file={yes*\|no}` | Load `startup.jl` (see [Section 5.4](#54-run-startup-code-automatically)) |
| `--handle-signals={yes*\|no}` | Enable or disable Julia's default signal handlers |
| `--sysimage-native-code={yes*\|no}` | Use native code from the system image if available |
| `-q`, `--quiet` | Quiet startup: no banner, suppress REPL warnings |
| `--banner={yes\|no\|short\|auto*}` | Enable or disable the startup banner |

### 6.2 Projects and code loading

| Switch | Description |
|---|---|
| `-P`, `--project[={<dir>\|@temp\|@.}]` | Set `<dir>` as the active project/environment. `@temp` creates a temporary environment. The default `@.` searches parent directories for a `Project.toml` or `JuliaProject.toml` |
| `--compiled-modules={yes*\|no\|existing\|strict}` | Enable/disable incremental precompilation. `existing` uses existing precompiled modules but creates none; `strict` is like `existing` but errors if no precompile file is found |
| `--pkgimages={yes*\|no\|existing}` | Enable/disable native-code caching as pkgimages. `existing` uses existing pkgimages but creates none |

### 6.3 Evaluating code

| Switch | Description |
|---|---|
| `-e`, `--eval <expr>` | Evaluate `<expr>` |
| `-E`, `--print <expr>` | Evaluate `<expr>` and display the result |
| `-m`, `--module <Package> [args]` | Run the `@main` entry point of `Package` with `args` |
| `-L`, `--load <file>` | Load `<file>` immediately on all processors |
| `-i`, `--interactive` | Interactive mode; REPL runs and `isinteractive()` is `true` |

### 6.4 Threads and parallelism

| Switch | Description |
|---|---|
| `-t`, `--threads {auto\|N[,auto\|M]}` | Enable N[+M] threads. N go to the `:default` threadpool; the optional M go to the `:interactive` threadpool. `auto` infers a useful default |
| `--gcthreads=N[,M]` | Use N threads for the GC mark phase and M (0 or 1) for concurrent sweeping. N defaults to the number of compute threads; M defaults to 0 |
| `-p`, `--procs {N\|auto}` | Launch N additional local worker processes; `auto` launches one per local CPU thread |
| `--machine-file <file>` | Run worker processes on hosts listed in `<file>` |

### 6.5 Code generation and optimization

| Switch | Description |
|---|---|
| `-O`, `--optimize={0\|1\|2*\|3}` | Set the optimization level (3 if `-O` is given without a level) **($)** |
| `--min-optlevel={0*\|1\|2\|3}` | Set a lower bound on per-module optimization |
| `-g`, `--debug-info={0\|1*\|2}` | Set debug-info generation level (2 if `-g` given without a level) **($)** |
| `--inline={yes*\|no}` | Control whether inlining is permitted (overrides `@inline`) |
| `--check-bounds={yes\|no\|auto*}` | Emit bounds checks always, never, or respecting `@inbounds` **($)** |
| `--math-mode={ieee\|user*}` | Always follow IEEE float semantics or respect `@fastmath` |
| `--polly={yes*\|no}` | Enable/disable the polyhedral optimizer Polly (overrides `@polly`) |
| `-C`, `--cpu-target <target>` | Limit CPU features up to `<target>`; use `-C help` to list options |
| `--compile={yes*\|no\|all\|min}` | Enable/disable the JIT compiler, or request exhaustive/minimal compilation |
| `--image-codegen` | Force code generation in imaging mode |
| `--permalloc-pkgimg={yes\|no*}` | Copy the data section of package images into memory |

### 6.6 Warnings

| Switch | Description |
|---|---|
| `--depwarn={yes\|no*\|error}` | Enable/disable deprecation warnings (`error` turns them into errors) |
| `--warn-overwrite={yes\|no*}` | Enable/disable method-overwrite warnings |
| `--warn-scope={yes*\|no}` | Enable/disable warnings for ambiguous top-level scope |
| `--color={yes\|no\|auto*}` | Enable/disable colored text |
| `--history-file={yes*\|no}` | Load or save REPL history |

### 6.7 Memory and garbage collection

| Switch | Description |
|---|---|
| `--heap-size-hint=<size>` | Force GC when memory usage exceeds `<size>` (bytes, or with units `KB`/`MB`/`GB`/`TB`, or a `%` of physical memory) |

### 6.8 Profiling and tracing

| Switch | Description |
|---|---|
| `--code-coverage[={none*\|user\|all}]` | Count executions of source lines (omitting the value = `user`) |
| `--code-coverage=@<path>` | Count executions only in files under `<path>` (the `@` prefix is required) |
| `--code-coverage=tracefile.info` | Append coverage to an LCOV tracefile |
| `--track-allocation[={none*\|user\|all}]` | Count bytes allocated per source line (omitting the value = `user`) |
| `--track-allocation=@<path>` | Track allocations only in files under `<path>` (the `@` prefix is required) |
| `--task-metrics={yes\|no*}` | Enable collection of per-task metrics |
| `--trace-compile={stderr\|name}` | Print precompile statements for compiled methods, to stderr or a path. Recompiled methods are shown in yellow |
| `--trace-compile-timing` | With `--trace-compile`, show how long each method took to compile (ms) |
| `--trace-dispatch={stderr\|name}` | Print precompile statements for dispatched methods |
| `--trace-eval[={no*\|loc\|full}]` | Show top-level expressions being evaluated (`loc` = location only, `full` = full expression) |
| `--bug-report=KIND` | Launch a bug-report session via BugReporting.jl; see `--bug-report=help` |

### 6.9 System-image / static-output generation

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

| Switch | Description |
|---|---|
| `--output-o <name>` | Generate an object file (including system image data) |
| `--output-ji <name>` | Generate a system image data file (`.ji`) |
| `--output-unopt-bc <name>` | Generate unoptimized LLVM bitcode (`.bc`) |
| `--output-bc <name>` | Generate LLVM bitcode (`.bc`) |
| `--output-asm <name>` | Generate an assembly file (`.s`) |
| `--output-incremental={yes\|no*}` | Generate an incremental output file rather than a complete one |
| `--strip-metadata` | Remove docstrings and source-location info from the system image |
| `--strip-ir` | Remove the IR of compiled functions from the system image |
| `--trim={no*\|safe\|unsafe\|unsafe-warn}` | Build a sysimage including only code provably reachable from `entrypoint`-marked methods. `safe` errors on dynamic call sites; `unsafe` allows them (binary may be missing code); `unsafe-warn` warns but allows them |

---

## 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`](#parallelization), [`JULIA_PROJECT`](#file-locations), and [`JULIA_DEPOT_PATH`](#file-locations). 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

| Variable | Purpose |
|---|---|
| `JULIA_BINDIR` | Absolute path of the directory containing the `julia` executable; sets `Sys.BINDIR`. Determined at runtime if unset |
| `JULIA_PROJECT` | Initial active project. Same effect as `--project`, but `--project` wins. `@.` searches parents for `Project.toml`/`JuliaProject.toml`. **Must be set before startup** |
| `JULIA_LOAD_PATH` | Populates `LOAD_PATH` (which packages can be loaded). Empty entries expand to the default `["@", "@v#.#", "@stdlib"]`. Separator is `:` (Unix) / `;` (Windows) |
| `JULIA_DEPOT_PATH` | Populates `DEPOT_PATH` (where packages, registries, caches, config, and REPL history live). Trailing `:` overrides the user depot while keeping bundled resources. **Must be set before startup** |
| `JULIA_HISTORY` | Absolute path of the REPL history file (default `$(DEPOT_PATH[1])/logs/repl_history.jl`) |
| `JULIA_MAX_NUM_PRECOMPILE_FILES` | Max cached instances of a single package (default `10`) |
| `JULIA_VERBOSE_LINKING` | If true, show linker commands during precompilation |

### Package manager (Pkg.jl)

| Variable | Purpose |
|---|---|
| `JULIA_CI` | If `true`, signals to the package server that operations are part of CI |
| `JULIA_NUM_PRECOMPILE_TASKS` | Number of parallel tasks used when precompiling packages |
| `JULIA_PKG_DEVDIR` | Default directory used by `Pkg.develop` |
| `JULIA_PKG_IGNORE_HASHES` | If `1`, ignore incorrect artifact hashes (disables download verification — use with care) |
| `JULIA_PKG_OFFLINE` | If `true`, enable Pkg offline mode |
| `JULIA_PKG_PRECOMPILE_AUTO` | If `0`, disable automatic precompilation after manifest-changing actions |
| `JULIA_PKG_SERVER` | Package registry URL (default `https://pkg.julialang.org`). Set to `""` to bypass the PkgServer protocol |
| `JULIA_PKG_SERVER_REGISTRY_PREFERENCE` | `conservative` (default) or `eager` registry flavor |
| `JULIA_PKG_UNPACK_REGISTRY` | If `true`, unpack the registry instead of storing a compressed tarball |
| `JULIA_PKG_USE_CLI_GIT` | If `true`, use an external `git` executable instead of libgit2 |
| `JULIA_PKGRESOLVE_ACCURACY` | Positive integer; accuracy of the resolver (default `1`) |
| `JULIA_PKG_PRESERVE_TIERED_INSTALLED` | Prefer keeping already-installed package versions during installs |
| `JULIA_PKG_GC_AUTO` | If `false`, disable automatic GC of packages/artifacts (Julia 1.12+) |

### Network transport

| Variable | Purpose |
|---|---|
| `JULIA_NO_VERIFY_HOSTS` / `JULIA_SSL_NO_VERIFY_HOSTS` / `JULIA_SSH_NO_VERIFY_HOSTS` / `JULIA_ALWAYS_VERIFY_HOSTS` | Hosts whose identity should or should not be verified, per transport layer |
| `JULIA_SSL_CA_ROOTS_PATH` | File or directory of certificate-authority roots |

### External applications

| Variable | Purpose |
|---|---|
| `JULIA_SHELL` | Shell used to run external commands (default `$SHELL`, then `/bin/sh`). Ignored on Windows |
| `JULIA_EDITOR` | Preferred editor for `InteractiveUtils.edit`. Takes precedence over `$VISUAL`, then `$EDITOR`. On Windows, set to `code.cmd` to use VS Code |

### Parallelization

| Variable | Purpose |
|---|---|
| `JULIA_CPU_THREADS` | Override `Sys.CPU_THREADS` (number of logical cores) |
| `JULIA_WORKER_TIMEOUT` | Seconds a worker waits for the master before dying (default `60.0`) |
| `JULIA_NUM_THREADS` | Max threads. `auto` = number of CPU threads; `N,M` sets `:default` and `:interactive` pool sizes. **Must be set before startup** |
| `JULIA_THREAD_SLEEP_THRESHOLD` | Nanoseconds before spinning threads sleep; `"infinite"` = never sleep |
| `JULIA_NUM_GC_THREADS` | Number of GC threads (default = number of worker threads) |
| `JULIA_IMAGE_THREADS` | Threads used by image compilation |
| `JULIA_IMAGE_TIMINGS` | If true, print detailed image-compilation timing |
| `JULIA_EXCLUSIVE` | If non-`0`, affinitize default-pool threads (dedicated-machine policy) |

### Garbage collection

| Variable | Purpose |
|---|---|
| `JULIA_HEAP_SIZE_HINT` | Same as `--heap-size-hint`. Force GC above a size (units `B`/`K`/`M`/`G`/`T` or `%`) |

### REPL formatting

| Variable | Default | Purpose |
|---|---|---|
| `JULIA_ERROR_COLOR` | light red `\033[91m` | Color for errors |
| `JULIA_WARN_COLOR` | yellow `\033[93m` | Color for warnings |
| `JULIA_INFO_COLOR` | cyan `\033[36m` | Color for info messages |
| `JULIA_INPUT_COLOR` | normal `\033[0m` | Color for input |
| `JULIA_ANSWER_COLOR` | normal `\033[0m` | Color for output |
| `NO_COLOR` | — | If present and non-empty, disable colored REPL text |
| `FORCE_COLOR` | — | If present and non-empty, enable colored REPL text |

### System- and package-image building

| Variable | Purpose |
|---|---|
| `JULIA_CPU_TARGET` | Target machine architecture for **disk-cached** (pre)compiled images. Does not affect in-memory JIT. List valid values with `julia -C help`. Supports special keywords `sysimage`, `clone_all`, `base(N)`, `opt_size`, `min_size` |

### Debugging and profiling

| Variable | Purpose |
|---|---|
| `JULIA_DEBUG` | Enable debug logging for a file or module |
| `JULIA_PROFILE_PEEK_HEAP_SNAPSHOT` | Collect a heap snapshot via the profiling "peek" mechanism |
| `JULIA_TIMING_SUBSYSTEMS` | Enable/disable timing zones, e.g. `+GC,-INFERENCE` |
| `JULIA_GC_WAIT_FOR_DEBUGGER` | If non-`0`, GC waits for a debugger on critical errors (needs a GC-debug build) |
| `ENABLE_JITPROFILING` | If non-`0`, register a JIT-profiling event listener (needs a build with VTune/OProfile/Perf support) |
| `ENABLE_GDBLISTENER` | If non-`0`, enable GDB registration of Julia code on release builds |
| `JULIA_LLVM_ARGS` | Arguments passed to the LLVM backend |
| `JULIA_FALLBACK_REPL` | Force the fallback REPL instead of REPL.jl |

---

## 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](https://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`](#file-locations).

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

### 8.2 Selecting the active project

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

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

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

Equivalently, set [`JULIA_PROJECT`](#file-locations) before launch (note: `--project` takes precedence).

### 8.3 Managing packages in the REPL

Press `]` to enter Pkg mode:

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

Press <kbd>Backspace</kbd> at an empty Pkg prompt to return to the `julia>` prompt.

> [!TIP]
> For a fresh, isolated environment for a piece of work:
> ```bash
> 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](#6-command-line-options-reference) (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](https://docs.julialang.org/en/v1/manual/multi-threading/), [Distributed Computing](https://docs.julialang.org/en/v1/manual/distributed-computing/)) go deeper.

### 9.1 Threads (shared memory)

```bash
# Let Julia pick a sensible default
julia -t auto
```

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

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

```bash
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

```bash
julia --gcthreads=4,1
```

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

### 9.3 Worker processes (distributed memory)

```bash
# 4 extra local workers
julia -p 4
```

```bash
# One worker per local CPU thread
julia -p auto
```

```bash
# 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

```bash
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`](#garbage-collection) does the same.

### 9.5 Optimization levels and latency trade-offs

| Goal | Flag |
|---|---|
| Lowest startup latency, quick scripts | `-O0` or `-O1`, `--compile=min` |
| Balanced (default) | `-O2` |
| Maximum runtime performance | `-O3` |

> [!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

```bash
# 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`](#system--and-package-image-building) 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.

```text
  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)

| Directory | Contents |
|---|---|
| `base/` | The `Base` module — core of Julia's standard library, written in Julia |
| `cli/` | The command-line launcher / loader |
| `src/` | The language core and runtime (C/C++) |
| `stdlib/` | The bundled standard-library packages |
| `etc/` | The default `startup.jl` |
| `doc/src/` | Source of the user manual |
| `test/` | Test suites |

---

## 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 <kbd>Backspace</kbd> 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

| Key at empty prompt | Mode | Leave with |
|---|---|---|
| *(default)* | Julian (evaluate) | — |
| `?` | Help | <kbd>Backspace</kbd> |
| `]` | Pkg | <kbd>Backspace</kbd> |
| `;` | Shell | <kbd>Backspace</kbd> |

### 13.2 Exiting Julia

| Action | How |
|---|---|
| Quit the REPL | `exit()` or <kbd>Ctrl</kbd>+<kbd>D</kbd> |
| Set the exit code | Return a `Cint`-convertible value from `(@main)`, or call `exit(code)` |

### 13.3 Most-used launch commands

| Task | Command |
|---|---|
| Start the REPL | `julia` |
| Run a script | `julia script.jl` |
| Run a script with args | `julia -- script.jl a b` |
| Evaluate an expression | `julia -e 'expr'` |
| Evaluate and print | `julia -E 'expr'` |
| Use the current project | `julia --project=@.` |
| Multiple threads | `julia -t auto` |
| Quiet, no banner | `julia -q` |
| Max optimization | `julia -O3` |
| No startup file (reproducible) | `julia --startup-file=no` |
| Show version | `julia --version` |

### 13.4 Globals available to your code

| Global | Meaning |
|---|---|
| `ARGS` | Command-line arguments to your script (or to `-e`) |
| `PROGRAM_FILE` | Path of the running script (empty for `-e`) |
| `ans` | Value of the last evaluated expression (interactive only) |
| `ENV` | The process environment, as a dictionary |
| `LOAD_PATH` | Where `import`/`using` search for packages |
| `DEPOT_PATH` | Where packages, caches, and config live |

### 13.5 Where to go next

| Topic | Resource |
|---|---|
| The language manual | <https://docs.julialang.org> |
| Installing & version management | <https://julialang.org/install/> |
| Packages | <https://julialang.org/packages/> · <https://pkgdocs.julialang.org> |
| Learning resources | <https://julialang.org/learning/> |
| Help / community | Discourse, Zulip, Slack (links at <https://julialang.org>) |
| Building, embedding, internals | The companion **Admin Guide** |

---

_Generated June 2026 from JuliaLang/julia at 2614585. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._