11. API Reference

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:

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.

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.

Pkg.add(pkg::Union{String, Vector{String}})
Pkg.add(pkg::Union{PackageSpec, Vector{PackageSpec}})

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.

Examples

Pkg.add("Example") # Add a package from registry
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.

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

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")

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.

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.

Pkg.test(; coverage::Bool=false)
Pkg.test(pkg::Union{String, Vector{String}; coverage::Bool=false)
Pkg.test(pkgs::Union{PackageSpec, Vector{PackageSpec}}; coverage::Bool=false)

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"]

Coverage statistics for the packages may be generated by passing coverage=true. The default behavior is to not run coverage.

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.

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.

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"))

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"))

Pkg.instantiate()

If a Manifest.toml file exists in the current project, download all the packages declared in that manifest. Otherwise, resolve a set of feasible packages from the Project.toml files and install them.

Pkg.resolve()

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

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.

Pkg.status([pkgs...]; mode::PackageMode=PKGMODE_PROJECT)

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.

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")

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.

Examples

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

Pkg.Registry.add(url::String)
Pkg.Registry.add(registry::RegistrySpec)

Add new package registries.

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"))

Pkg.Registry.rm(registry::String)
Pkg.Registry.rm(registry::RegistrySpec)

Remove registries.

Examples

Pkg.Registry.rm("General")
Pkg.Registry.rm(RegistrySpec(uuid = "23338594-aafe-5451-b93e-139f81909106"))

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.

Examples

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

Pkg.Registry.status()

Display information about available registries.

Examples

Pkg.Registry.status()