What follows is a quick overview of the basic features of Pkg. It should help new users become familiar with basic Pkg features such as adding and removing packages and working with environments.
Some Pkg output is omitted in this section in order to keep this basic guide focused. This will help maintain a good pace and not get bogged down in details. If you require more details, refer to subsequent sections of the Pkg manual.
This guide uses the Pkg REPL to execute Pkg commands. For non-interactive use, we recommend the Pkg API. The Pkg API is fully documented in the API Reference section of the Pkg documentation.
Pkg comes with a REPL. Enter the Pkg REPL by pressing
] from the Julia REPL. To get back to the Julia REPL, press
Ctrl+C or backspace (when the REPL cursor is at the beginning of the input).
Upon entering the Pkg REPL, you should see the following prompt:
To add a package, use
(@v1.8) pkg> add Example Resolving package versions... Installed Example ─ v0.5.3 Updating `~/.julia/environments/v1.8/Project.toml` [7876af07] + Example v0.5.3 Updating `~/.julia/environments/v1.8/Manifest.toml` [7876af07] + Example v0.5.3
After the package is installed, it can be loaded into the Julia session:
julia> import Example julia> Example.hello("friend") "Hello, friend"
We can also specify multiple packages at once to install:
(@v1.8) pkg> add JSON StaticArrays
status command (or the shorter
st command) can be used to see installed packages.
(@v1.8) pkg> st Status `~/.julia/environments/v1.6/Project.toml` [7876af07] Example v0.5.3 [682c06a0] JSON v0.21.3 [90137ffa] StaticArrays v1.5.9
Some Pkg REPL commands have a short and a long version of the command, for example
To remove packages, use
(@v1.8) pkg> rm JSON StaticArrays
update) to update the installed packages
(@v1.8) pkg> up
If you have been following this guide it is likely that the packages installed are at the latest version so
up will not do anything. Below we show the status output in the case where we deliberately have installed an old version of the Example package and then upgrade it:
(@v1.8) pkg> st Status `~/.julia/environments/v1.8/Project.toml` ⌃ [7876af07] Example v0.5.1 Info Packages marked with ⌃ have new versions available and may be upgradable. (@v1.8) pkg> up Updating `~/.julia/environments/v1.8/Project.toml` [7876af07] ↑ Example v0.5.1 ⇒ v0.5.3
We can see that the status output tells us that there is a newer version available and that
up upgrades the package.
For more information about managing packages, see the Managing Packages section of the documentation.
Up to this point, we have covered basic package management: adding, updating, and removing packages.
You may have noticed the
(@v1.8) in the REPL prompt. This lets us know that
v1.8 is the active environment. Different environments can have different totally different packages and versions installed from another environment. The active environment is the environment that will be modified by Pkg commands such as
Let's set up a new environment so we may experiment. To set the active environment, use
(@v1.8) pkg> activate tutorial [ Info: activating new environment at `~/tutorial/Project.toml`.
Pkg lets us know we are creating a new environment and that this environment will be stored in the
~/tutorial directory. The path to the environment is created relative to the current working directory of the REPL.
Pkg has also updated the REPL prompt in order to reflect the new active environment:
We can ask for information about the active environment by using
(tutorial) pkg> status Status `~/tutorial/Project.toml` (empty environment)
~/tutorial/Project.toml is the location of the active environment's project file. A project file is a TOML file here Pkg stores the packages that have been explicitly installed. Notice this new environment is empty. Let us add some packages and observe:
(tutorial) pkg> add Example JSON ... (tutorial) pkg> status Status `~/tutorial/Project.toml` [7876af07] Example v0.5.3 [682c06a0] JSON v0.21.3
We can see that the
tutorial environment now contains
If you have the same package (at the same version) installed in multiple environments, the package will only be downloaded and stored on the hard drive once. This makes environments very lightweight and effectively free to create. Only using the default environment with a huge number of packages in it is a common beginners mistake in Julia. Learning how to use environments effectively will improve your experience with Julia packages.
For more information about environments, see the Working with Environments section of the documentation.
If you are ever stuck, you can ask
Pkg for help:
(@v1.8) pkg> ?
You should see a list of available commands along with short descriptions. You can ask for more detailed help by specifying a command:
(@v1.8) pkg> ?develop
This guide should help you get started with
Pkg has much more to offer in terms of powerful package management, read the full manual to learn more!