12. API Reference

12. API Reference

This section describes the function interface, or "API mode", for interacting with Pkg.jl. The function API is recommended for non-interactive usage, for example in scripts.

General API Reference

Certain options are generally useful and can be specified in any API call. You can specify these options by setting keyword arguments.

Redirecting output

Use the io::IOBuffer keyword argument to redirect Pkg output. For example, Pkg.add("Example"; io=devnull) will discard any output produced by the add call.

Package API Reference

In the REPL mode, packages (with associated version, UUID, URL etc) are parsed from strings, for example "Package#master","Package@v0.1", "www.mypkg.com/MyPkg#my/feature".

In the API mode, it is possible to use strings as arguments for simple commands (like Pkg.add(["PackageA", "PackageB"]), but more complicated commands, which e.g. specify URLs or version range, require the use of a more structured format over strings. This is done by creating an instance of PackageSpec which is passed in to functions.

Pkg.PackageSpecFunction.
PackageSpec(name::String, [uuid::UUID, version::VersionNumber])
PackageSpec(; name, url, path, rev, version, mode, level)

A PackageSpec is a representation of a package with various metadata. This includes:

  • The name of the package.
  • The package's unique uuid.
  • A version (for example when adding a package). When upgrading, can also be an instance of

the enum UpgradeLevel.

  • A url and an optional git revision. rev can be a branch name or a git commit SHA1.
  • A local path. This is equivalent to using the url argument but can be more descriptive.
  • A mode, which is an instance of the enum PackageMode, with possible values PKGMODE_PROJECT

(the default) or PKGMODE_MANIFEST. Used in e.g. Pkg.rm.

Most functions in Pkg take a Vector of PackageSpec and do the operation on all the packages in the vector.

Below is a comparison between the REPL version and the API version:

REPLAPI
PackagePackageSpec("Package")
Package@0.2PackageSpec(name="Package", version="0.2")
Package=a67d...PackageSpec(name="Package", uuid="a67d...")
Package#masterPackageSpec(name="Package", rev="master")
local/path#featurePackageSpec(path="local/path"; rev="feature")
www.mypkg.comPackageSpec(url="www.mypkg.com")
--manifest PackagePackageSpec(name="Package", mode=PKGSPEC_MANIFEST)
--major PackagePackageSpec(name="Package", version=PKGLEVEL_MAJOR)
source
Pkg.PackageModeType.
PackageMode

An enum with the instances

  • PKGMODE_MANIFEST
  • PKGMODE_PROJECT

Determines if operations should be made on a project or manifest level. Used as an argument to PackageSpec or as an argument to Pkg.rm.

source
UpgradeLevel

An enum with the instances

  • UPLEVEL_FIXED
  • UPLEVEL_PATCH
  • UPLEVEL_MINOR
  • UPLEVEL_MAJOR

Determines how much a package is allowed to be updated. Used as an argument to PackageSpec or as an argument to Pkg.update.

source
Pkg.addFunction.
Pkg.add(pkg::Union{String, Vector{String}}; preserve=PRESERVE_TIERED)
Pkg.add(pkg::Union{PackageSpec, Vector{PackageSpec}}; preserve=PRESERVE_TIERED)

Add a package to the current project. This package will be available by using the import and using keywords in the Julia REPL, and if the current project is a package, also inside that package.

Resolution Tiers

Pkg resolves the set of packages in your environment using a tiered algorithm. The preserve keyword argument allows you to key into a specific tier in the resolve algorithm. The following table describes the argument values for preserve (in order of strictness):

ValueDescription
PRESERVE_ALLPreserve the state of all existing dependencies (including recursive dependencies)
PRESERVE_DIRECTPreserve the state of all existing direct dependencies
PRESERVE_SEMVERPreserve semver-compatible versions of direct dependencies
PRESERVE_NONEDo not attempt to preserve any version information
PRESERVE_TIEREDUse the tier which will preserve the most version information (this is the default)

Examples

Pkg.add("Example") # Add a package from registry
Pkg.add("Example"; preserve=Pkg.PRESERVE_ALL) # Add the `Example` package and preserve existing dependencies
Pkg.add(PackageSpec(name="Example", version="0.3")) # Specify version; latest release in the 0.3 series
Pkg.add(PackageSpec(name="Example", version="0.3.1")) # Specify version; exact release
Pkg.add(PackageSpec(url="https://github.com/JuliaLang/Example.jl", rev="master")) # From url to remote gitrepo
Pkg.add(PackageSpec(url="/remote/mycompany/juliapackages/OurPackage")) # From path to local gitrepo

See also PackageSpec.

source
Pkg.developFunction.
Pkg.develop(pkg::Union{String, Vector{String}})
Pkg.develop(pkgs::Union{Packagespec, Vector{Packagespec}})

Make a package available for development by tracking it by path. If pkg is given with only a name or by a URL, the package will be downloaded to the location specified by the environment variable JULIA_PKG_DEVDIR, with .julia/dev as the default.

If pkg is given as a local path, the package at that path will be tracked.

Examples

# By name
Pkg.develop("Example")

# By url
Pkg.develop(PackageSpec(url="https://github.com/JuliaLang/Compat.jl"))

# By path
Pkg.develop(PackageSpec(path="MyJuliaPackages/Package.jl"))

See also PackageSpec

source
Pkg.activateFunction.
Pkg.activate([s::String]; shared::Bool=false)

Activate the environment at s. The active environment is the environment that is modified by executing package commands. The logic for what path is activated is as follows:

  • If shared is true, the first existing environment named s from the depots in the depot stack will be activated. If no such environment exists, create and activate that environment in the first depot.
  • If s is an existing path, then activate the environment at that path.
  • If s is a package in the current project and s is tracking a path, then activate the environment at the tracked path.
  • Otherwise, s is interpreted as a non-existing path, which is then activated.

If no argument is given to activate, then activate the home project. The home project is specified by either the --project command line option to the julia executable, or the JULIA_PROJECT environment variable.

Examples

Pkg.activate()
Pkg.activate("local/path")
Pkg.activate("MyDependency")
source
Pkg.rmFunction.
Pkg.rm(pkg::Union{String, Vector{String}})
Pkg.rm(pkg::Union{PackageSpec, Vector{PackageSpec}})

Remove a package from the current project. If the mode of pkg is PKGMODE_MANIFEST also remove it from the manifest including all recursive dependencies of pkg.

See also PackageSpec, PackageMode.

source
Pkg.updateFunction.
Pkg.update(; level::UpgradeLevel=UPLEVEL_MAJOR, mode::PackageMode = PKGMODE_PROJECT)
Pkg.update(pkg::Union{String, Vector{String}})
Pkg.update(pkg::Union{PackageSpec, Vector{PackageSpec}})

Update a package pkg. If no posistional argument is given, update all packages in the manifest if mode is PKGMODE_MANIFEST and packages in both manifest and project if mode is PKGMODE_PROJECT. If no positional argument is given, level can be used to control by how much packages are allowed to be upgraded (major, minor, patch, fixed).

See also PackageSpec, PackageMode, UpgradeLevel.

source
Pkg.testFunction.
Pkg.test(; kwargs...)
Pkg.test(pkg::Union{String, Vector{String}; kwargs...)
Pkg.test(pkgs::Union{PackageSpec, Vector{PackageSpec}}; kwargs...)

Keyword arguments:

  • coverage::Bool=false: enable or disable generation of coverage statistics.
  • julia_args::Union{Cmd, Vector{String}}: options to be passed the test process.
  • test_args::Union{Cmd, Vector{String}}: test arguments (ARGS) available in the test process.
Julia 1.3

julia_args and test_args requires at least Julia 1.3.

Run the tests for package pkg, or for the current project (which thus needs to be a package) if no positional argument is given to Pkg.test. A package is tested by running its test/runtests.jl file.

The tests are run by generating a temporary environment with only pkg and its (recursive) dependencies in it. If a manifest exists, the versions in that manifest are used, otherwise a feasible set of packages is resolved and installed.

During the tests, test-specific dependencies are active, which are given in the project file as e.g.

[extras]
Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

[targets]
test = ["Test"]

The tests are executed in a new process with check-bounds=yes and by default startup-file=no. If using the startup file (~/.julia/config/startup.jl) is desired, start julia with --startup-file=yes. Inlining of functions during testing can be disabled (for better coverage accuracy) by starting julia with --inline=no.

source
Pkg.buildFunction.
Pkg.build(; verbose = false)
Pkg.build(pkg::Union{String, Vector{String}}; verbose = false)
Pkg.build(pkgs::Union{PackageSpec, Vector{PackageSpec}}; verbose = false)

Run the build script in deps/build.jl for pkg and all of its dependencies in depth-first recursive order. If no argument is given to build, the current project is built, which thus needs to be a package. This function is called automatically on any package that gets installed for the first time. verbose = true prints the build output to stdout/stderr instead of redirecting to the build.log file.

source
Pkg.pinFunction.
Pkg.pin(pkg::Union{String, Vector{String}})
Pkg.pin(pkgs::Union{PackageSpec, Vector{PackageSpec}})

Pin a package to the current version (or the one given in the PackageSpec) or to a certain git revision. A pinned package is never updated.

Examples

Pkg.pin("Example")
Pkg.pin(PackageSpec(name="Example", version="0.3.1"))
source
Pkg.freeFunction.
Pkg.free(pkg::Union{String, Vector{String}})
Pkg.free(pkgs::Union{PackageSpec, Vector{PackageSpec}})

If pkg is pinned, remove the pin. If pkg is tracking a path, e.g. after Pkg.develop, go back to tracking registered versions.

Examples

Pkg.free("Package")
Pkg.free(PackageSpec("Package"))
source
Pkg.instantiateFunction.
Pkg.instantiate(; verbose = false)

If a Manifest.toml file exists in the active project, download all the packages declared in that manifest. Otherwise, resolve a set of feasible packages from the Project.toml files and install them. verbose = true prints the build output to stdout/stderr instead of redirecting to the build.log file. If no Project.toml exist in the current active project, create one with all the dependencies in the manifest and instantiate the resulting project.

source
Pkg.resolveFunction.
Pkg.resolve()

Update the current manifest with potential changes to the dependency graph from packages that are tracking a path.

source
Pkg.gcFunction.
Pkg.gc()

Garbage collect packages that are no longer reachable from any project. Only packages that are tracked by version are deleted, so no packages that might contain local changes are touched.

source
Pkg.statusFunction.
Pkg.status([pkgs...]; mode::PackageMode=PKGMODE_PROJECT, diff::Bool=false)

Print out the status of the project/manifest. If mode is PKGMODE_PROJECT, print out status only about the packages that are in the project (explicitly added). If mode is PKGMODE_MANIFEST, print status also about those in the manifest (recursive dependencies). If there are any packages listed as arguments, the output will be limited to those packages. Setting diff=true will, if the environment is in a git repository, limit the output to the difference as compared to the last git commit.

Julia 1.1

Pkg.status with package arguments requires at least Julia 1.1.

Julia 1.3

The diff keyword argument requires Julia 1.3. In earlier versions diff=true is the default for environments in git repositories.

source
Pkg.precompileFunction.
Pkg.precompile()

Precompile all the dependencies of the project.

Julia 1.3

This function requires at least Julia 1.3. On earlier versions you can use Pkg.API.precompile() or the precompile Pkg REPL command.

Examples

Pkg.precompile()
source
Pkg.setprotocol!Function.
setprotocol!(;
    domain::AbstractString = "github.com",
    protocol::Union{Nothing, AbstractString}=nothing
)

Set the protocol used to access hosted packages when adding a url or developing a package. Defaults to delegating the choice to the package developer (protocol === nothing). Other choices for protocol are "https" or "git".

Examples

julia> Pkg.setprotocol!(domain = "github.com", protocol = "ssh")

julia> Pkg.setprotocol!(domain = "gitlab.mycompany.com")
source
Pkg.dependenciesFunction.
Pkg.dependencies()::Dict{UUID, PackageInfo}
Julia 1.4

This feature requires Julia 1.4, and is considered experimental.

Query the dependecy graph. The result is a Dict that maps a package UUID to a PackageInfo struct representing the dependency (a package).

PackageInfo fields

FieldDescription
nameThe name of the package
versionThe version of the package (this is Nothing for stdlibs)
isdevelopedWhether a package is directly tracking a directory
ispinnedWhether a package is pinned
sourceThe directory containing the source code for that package
dependenciesThe dependencies of that package as a vector of UUIDs
source
Pkg.projectFunction.
Pkg.project()::ProjectInfo
Julia 1.4

This feature requires Julia 1.4, and is considered experimental.

Request a ProjectInfo struct which contains information about the active project.

ProjectInfo fields

FieldDescription
nameThe project's name
uuidThe project's UUID
versionThe project's version
dependenciesThe project's direct dependencies as a Dict which maps dependency name to dependency UUID
pathThe location of the project file which defines the active project
source
Pkg.undoFunction.
undo()

Undoes the latest change to the active project. Only states in the current session are stored, up to a maximum of 50 states.

See also: redo.

source
Pkg.redoFunction.
redo()

Redoes the changes from the latest undo.

source

Registry API Reference

Julia 1.1

Pkg's registry handling requires at least Julia 1.1.

The function API for registries uses RegistrySpecs, similar to PackageSpec.

RegistrySpec(name::String)
RegistrySpec(; name, url, path)

A RegistrySpec is a representation of a registry with various metadata, much like PackageSpec.

Most registry functions in Pkg take a Vector of RegistrySpec and do the operation on all the registries in the vector.

Julia 1.1

Pkg's registry handling requires at least Julia 1.1.

Examples

Below is a comparison between the REPL version and the API version:

REPLAPI
RegistryRegistrySpec("Registry")
Registry=a67d...RegistrySpec(name="Registry", uuid="a67d...")
local/pathRegistrySpec(path="local/path")
www.myregistry.comRegistrySpec(url="www.myregistry.com")
source
Pkg.Registry.addFunction.
Pkg.Registry.add(url::String)
Pkg.Registry.add(registry::RegistrySpec)

Add new package registries.

Julia 1.1

Pkg's registry handling requires at least Julia 1.1.

Examples

Pkg.Registry.add("General")
Pkg.Registry.add(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
Pkg.Registry.add(RegistrySpec(url = "https://github.com/JuliaRegistries/General.git"))
source
Pkg.Registry.rmFunction.
Pkg.Registry.rm(registry::String)
Pkg.Registry.rm(registry::RegistrySpec)

Remove registries.

Julia 1.1

Pkg's registry handling requires at least Julia 1.1.

Examples

Pkg.Registry.rm("General")
Pkg.Registry.rm(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
source
Pkg.Registry.updateFunction.
Pkg.Registry.update()
Pkg.Registry.update(registry::RegistrySpec)
Pkg.Registry.update(registry::Vector{RegistrySpec})

Update registries. If no registries are given, update all available registries.

Julia 1.1

Pkg's registry handling requires at least Julia 1.1.

Examples

Pkg.Registry.update()
Pkg.Registry.update("General")
Pkg.Registry.update(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))
source
Pkg.Registry.statusFunction.
Pkg.Registry.status()

Display information about available registries.

Julia 1.1

Pkg's registry handling requires at least Julia 1.1.

Examples

Pkg.Registry.status()
source

Artifacts API Reference

Julia 1.3

Pkg's artifacts API requires at least Julia 1.3.

create_artifact(f::Function)

Creates a new artifact by running f(artifact_path), hashing the result, and moving it to the artifact store (~/.julia/artifacts on a typical installation). Returns the identifying tree hash of this artifact.

Julia 1.3

This function requires at least Julia 1.3.

source
artifact_exists(hash::SHA1; honor_overrides::Bool=true)

Returns whether or not the given artifact (identified by its sha1 git tree hash) exists on-disk. Note that it is possible that the given artifact exists in multiple locations (e.g. within multiple depots).

Julia 1.3

This function requires at least Julia 1.3.

source
artifact_path(hash::SHA1; honor_overrides::Bool=true)

Given an artifact (identified by SHA1 git tree hash), return its installation path. If the artifact does not exist, returns the location it would be installed to.

Julia 1.3

This function requires at least Julia 1.3.

source
remove_artifact(hash::SHA1; honor_overrides::Bool=false)

Removes the given artifact (identified by its SHA1 git tree hash) from disk. Note that if an artifact is installed in multiple depots, it will be removed from all of them. If an overridden artifact is requested for removal, it will be silently ignored; this method will never attempt to remove an overridden artifact.

In general, we recommend that you use Pkg.gc() to manage artifact installations and do not use remove_artifact() directly, as it can be difficult to know if an artifact is being used by another package.

Julia 1.3

This function requires at least Julia 1.3.

source
verify_artifact(hash::SHA1; honor_overrides::Bool=false)

Verifies that the given artifact (identified by its SHA1 git tree hash) is installed on- disk, and retains its integrity. If the given artifact is overridden, skips the verification unless honor_overrides is set to true.

Julia 1.3

This function requires at least Julia 1.3.

source
artifact_meta(name::String, artifacts_toml::String;
              platform::Platform = platform_key_abi(),
              pkg_uuid::Union{Base.UUID,Nothing}=nothing)

Get metadata about a given artifact (identified by name) stored within the given (Julia)Artifacts.toml file. If the artifact is platform-specific, use platform to choose the most appropriate mapping. If none is found, return nothing.

Julia 1.3

This function requires at least Julia 1.3.

source
artifact_hash(name::String, artifacts_toml::String; platform::Platform = platform_key_abi())

Thin wrapper around artifact_meta() to return the hash of the specified, platform- collapsed artifact. Returns nothing if no mapping can be found.

Julia 1.3

This function requires at least Julia 1.3.

source
bind_artifact!(artifacts_toml::String, name::String, hash::SHA1;
               platform::Union{Platform,Nothing} = nothing,
               download_info::Union{Vector{Tuple},Nothing} = nothing,
               lazy::Bool = false,
               force::Bool = false)

Writes a mapping of name -> hash within the given (Julia)Artifacts.toml file. If platform is not nothing, this artifact is marked as platform-specific, and will be a multi-mapping. It is valid to bind multiple artifacts with the same name, but different platforms and hash'es within the same artifacts_toml. If force is set to true, this will overwrite a pre-existant mapping, otherwise an error is raised.

download_info is an optional tuple that contains a vector of URLs and a hash. These URLs will be listed as possible locations where this artifact can be obtained. If lazy is set to true, even if download information is available, this artifact will not be downloaded until it is accessed via the artifact"name" syntax, or ensure_artifact_installed() is called upon it.

Julia 1.3

This function requires at least Julia 1.3.

source
unbind_artifact!(artifacts_toml::String, name::String; platform = nothing)

Unbind the given name from an (Julia)Artifacts.toml file. Silently fails if no such binding exists within the file.

Julia 1.3

This function requires at least Julia 1.3.

source
download_artifact(tree_hash::SHA1, tarball_url::String, tarball_hash::String;
                  verbose::Bool = false)

Download/install an artifact into the artifact store. Returns true on success.

Julia 1.3

This function requires at least Julia 1.3.

source
find_artifacts_toml(path::String)

Given the path to a .jl file, (such as the one returned by __source__.file in a macro context), find the (Julia)Artifacts.toml that is contained within the containing project (if it exists), otherwise return nothing.

Julia 1.3

This function requires at least Julia 1.3.

source
ensure_artifact_installed(name::String, artifacts_toml::String;
                          platform::Platform = platform_key_abi(),
                          pkg_uuid::Union{Base.UUID,Nothing}=nothing)

Ensures an artifact is installed, downloading it via the download information stored in artifacts_toml if necessary. Throws an error if unable to install.

Julia 1.3

This function requires at least Julia 1.3.

source
ensure_all_artifacts_installed(artifacts_toml::String;
                               platform = platform_key_abi(),
                               pkg_uuid = nothing,
                               include_lazy = false,
                               verbose = false)

Installs all non-lazy artifacts from a given (Julia)Artifacts.toml file. package_uuid must be provided to properly support overrides from Overrides.toml entries in depots.

If include_lazy is set to true, then lazy packages will be installed as well.

Julia 1.3

This function requires at least Julia 1.3.

source
macro artifact_str(name)

Macro that is used to automatically ensure an artifact is installed, and return its location on-disk. Automatically looks the artifact up by name in the project's (Julia)Artifacts.toml file. Throws an error on inability to install the requested artifact.

Julia 1.3

This macro requires at least Julia 1.3.

source
archive_artifact(hash::SHA1, tarball_path::String; honor_overrides::Bool=false)

Archive an artifact into a tarball stored at tarball_path, returns the SHA256 of the resultant tarball as a hexidecimal string. Throws an error if the artifact does not exist. If the artifact is overridden, throws an error unless honor_overrides is set.

Julia 1.3

This function requires at least Julia 1.3.

source