PackageInitialize
PackageInitialize["context`"]
creates the given package context and loads the surrounding files into it.
PackageInitialize["context`",dir]
creates the given package context and loads the files in dir into it.
PackageInitialize["context`",file]
reloads a single file from a previously loaded package.
PackageInitialize["context`",None]
creates the given package context by using only the file currently being read.
PackageInitialize["context`",<prop1val1,prop2val2,…>]
creates the given package context and loads the surrounding files into it, with behavior specified by propivali.
Details
- PackageInitialize is called by package developers to load their packages that are implemented in the Structured Package Format.
- PackageInitialize is typically called in one file of a package, called the "loader file", which acts to load all the other source files of the package.
- PackageInitialize creates the given context and reads in all Wolfram Language files in the same directory or subdirectories up to three levels deep.
- PackageInitialize["context`",dir] loads the files from the given directory and its subdirectories.
- PackageInitialize["context`",file] reloads a single file from an already loaded package, which can be useful during development.
- PackageInitialize["context`",None] is a special form used to create single-file packages, where the source code for the package is in the same file as the call to PackageInitialize.
- PackageInitialize is only of interest to package developers, not package users.
- PackageInitialize takes an optional Association of properties that control its behavior:
-
"ExtraPublicContexts" {} extra contexts you want to load and leave on $ContextPath after your package loads "FileOrderingFunction" Automatic ordering of files to load (defaults to alphabetic) "HiddenImports" {} other packages that should be visible within all files of your package "IgnoreFiles" {} files to completely ignore, as if they were not present "LoadFirstFiles" {} files to load first, before other files "LoadLastFiles" {} files to load last, after other files "SkipLoadingFiles" {} files that will be scanned along with the rest of the package files, but never actually evaluated "SymbolsToProtect" {} symbols that you want to give the Protected attribute to after the package loads
Examples
open all close allBasic Examples (3)
PackageInitialize is primarily used within a file of code, but in advanced usage it can also be called from an interactive prompt. When used this way, it requires a second argument to supply the directory of source files to load:
PackageInitialize["PackageFormatExample`"]
This loads an example package written in the Structured Package Format style by giving the location of its files as the second argument to PackageInitialize:
PackageInitialize ["PackageFormatExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"]]The package has been loaded and added to $ContextPath:
MemberQ[$ContextPath, "PackageFormatExample`"]Note that the context used in the PackageInitialize call is "PackageFormatExample`", whereas the SPFExample directory has its own init.wl loader file that uses the context "SPFExample`". When using PackageInitialize to point at a directory, you automatically bypass any init.wl loader file that might exist within that directory, in effect doing a "manual" load of the package using whatever context or other special behavior of PackageInitialize that you choose.
You can use PackageInitialize to reload a single file from a previously loaded package, for example during iterative development of a package, where you want to avoid reloading the entire package each time:
AppendTo[$Path, FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData"]];The package needs to be fully loaded once:
Needs["SPFExample`"]Now reload a single file, as if it had changed since the previous load:
PackageInitialize ["SPFExample`", "SPFExample/PackageFile2.wl"]Although the Structured Package Format is intended primarily for multi-file packages, you can also create single-file packages, where all the code for the package, along with the PackageInitialize call, is in one file. Using None as the second argument to PackageInitialize tells it to ignore any other files and take the entire contents of the package to be just the code in the file following the PackageInitialize call.
Here is the source for a trivial single-file package that exports the function Function1:
PackageInitialize["SingleFilePackageExample`", None]
PackageExported[Function1]
Function1[x_] := privateFunc[x] + 1
privateFunc[x_] := x^2
The code that follows the PackageInitialize["MyPackage`",None] call can make use of all the features of the SPF.
Get["ExampleData/SingleFilePackageExample.wl"]Call the exported function Function1:
Function1[2]Scope (10)
The SPFExample directory in ExampleData contains an extremely simple package in the Structured Package Format (SPF) style. This is the one-line contents of the init.wl file:
PackageInitialize["SPFExample`"]
When the init.wl file loads, PackageInitialize gathers up the surrounding source files and loads them to become the SPFExample` package.
This is the contents of the PackageFile1.wl file:
PackageExported[Func1]
Func1[x_] := x+1
PackageScoped[utilFunc]
utilFunc[n_] := n^2
This is the contents of the PackageFile2.wl file:
PackageExported[Func2]
Func2[x_] := utilFunc[x]
This package exports the symbols Func1 and Func2, meaning that they will be visible in a user's session after it loads.
Users of a package typically load it with Needs. Because this example package is not in a directory that is part of the package search path, first add it to $Path so that it can be found via a context name:
AppendTo[$Path, FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData"]];Now load the package in the usual way:
Needs["SPFExample`"]Func1[2]PackageInitialize does not take options in the traditional sense, but rather an association of properties that control its behavior. You can think of them as options, however, and in fact you can specify them using options-style syntax, not wrapped in an association.
"ExtraPublicContexts" (1)
Using "ExtraPublicContexts" is similar to the second argument to BeginPackage—it lets you specify that certain other contexts will be loaded, made visible throughout all the files in your package and also left on $ContextPath after your package finishes loading.
Load the sample package and also load and make visible the HypothesisTesting` package:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"ExtraPublicContexts" -> "HypothesisTesting`"|>]The HypothesisTesting` package has been loaded and made public, as if the user had called Needs on it themself:
MemberQ[$ContextPath, "HypothesisTesting`"]Contrast "ExtraPublicContexts" with the much more commonly used "HiddenImports" property, which does not leave the named contexts on the user's $ContextPath. In general, packages should not put contexts other than their own on $ContextPath.
"FileOrderingFunction" (1)
The "FileOrderingFunction" property lets you specify a function to sort the filenames of your package into the order in which they will be read. The default behavior is alphabetical ordering, so a filename starting with "A" will be read before a filename starting with "B".
The value of "FileOrderingFunction" should be an ordering function as described in the documentation for Sort.
Load the sample package by reading its files in order of shortest filename to longest:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"FileOrderingFunction" -> (StringLength[#1] <= StringLength[#2]&)|>]"HiddenImports" (1)
The "HiddenImports" property provides an easy way to specify contexts that should be loaded and visible in all files of a package.
Contexts specified as "HiddenImports" are not visible on a user's $ContextPath after the package is loaded, unlike with the "ExtraPublicContexts" property.
The following command is equivalent to putting a Needs["HypothesisTesting`"] in each of the package's source files:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"HiddenImports" -> "HypothesisTesting`"|>]The HypothesisTesting` package is not on the user's $ContextPath after loading:
MemberQ[$ContextPath, "HypothesisTesting`"]"IgnoreFiles" (1)
The "IgnoreFiles" property lets you specify files that should be completely ignored while loading a package, as if they were not present at all.
PackageInitialize by default will sweep up all Wolfram Language files (.m and .wl files) in the package directory and subdirectories. Use "IgnoreFiles" to cause certain files to be skipped:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"IgnoreFiles" -> {"PackageFile1.wl"}|>]"LoadFirstFiles" (1)
The "LoadFirstFiles" property lets you specify files that should be loaded ahead of any other files in the package. You might have a file that performs some initialization, or defines some symbols that need to have values while the rest of the package files are loaded.
This makes sure that PackageFile2.wl is loaded before PackageFile1.wl, even though the default file order would have PackageFile1.wl loaded first:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"LoadFirstFiles" -> {"PackageFile2.wl"}|>]"LoadLastFiles" (1)
The "LoadLastFiles" property lets you specify files that should be loaded after all the other files in the package. You might have a file that performs some final steps at the end of package loading, and you want to make sure it loads last.
This makes sure that PackageFile1.wl is loaded after PackageFile2.wl, even though the default file order would have PackageFile1.wl loaded first:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"LoadLastFiles" -> {"PackageFile1.wl"}|>]"SkipLoadingFiles" (1)
The "SkipLoadingFiles" property allows you to specify files that should be examined but not loaded during the package-loading procedure. The Structured Package Format uses a two-pass loading system internally, where files are examined once to determine metadata like their imports and exports, and then loaded for evaluation in the second pass. "SkipLoadingFiles" skips the second evaluation pass:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"SkipLoadingFiles" -> {"PackageFile2.wl"}|>]"SkipLoadingFiles" is an advanced property. Most developers who want to exclude certain .wl or .m files from their package should instead use the "IgnoreFiles" property.
"SymbolsToProtect" (1)
The "SymbolsToProtect" property lets you specify the string names of symbols from the package to make Protected and ReadProtected after the package loads:
PackageInitialize ["SPFExample`", FileNameJoin[$InstallationDirectory, "Documentation", "English", "System", "ExampleData", "SPFExample"], <|"SymbolsToProtect" -> {"Func1"}|>]Attributes[Func1]Use "SymbolsToProtect"All to protect all the exported symbols from a package.
Text
Wolfram Research (2026), PackageInitialize, Wolfram Language function, https://reference.wolfram.com/language/ref/PackageInitialize.html.
CMS
Wolfram Language. 2026. "PackageInitialize." Wolfram Language & System Documentation Center. Wolfram Research. https://reference.wolfram.com/language/ref/PackageInitialize.html.
APA
Wolfram Language. (2026). PackageInitialize. Wolfram Language & System Documentation Center. Retrieved from https://reference.wolfram.com/language/ref/PackageInitialize.html