# Pkg

Pkg is Julia's builtin package manager, and handles operations such as installing, updating and removing packages.

Note

What follows is a very brief introduction to Pkg. For more information on `Project.toml` files, `Manifest.toml` files, package version compatibility (`[compat]`), environments, registries, etc., it is highly recommended to read the full manual, which is available here: https://pkgdocs.julialang.org.

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.

Note

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.

Note

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:

    (@v1.8) pkg>

To add a package, use `add`:

    (@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

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

Note

Some Pkg REPL commands have a short and a long version of the command, for example `status` and `st`.

To remove packages, use `rm` (or `remove`):

    (@v1.8) pkg> rm JSON StaticArrays

Use `up` (or `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 `add`, `rm` and `update`.

Let's set up a new environment so we may experiment. To set the active environment, use `activate`:

    (@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:

    (tutorial) pkg>

We can ask for information about the active environment by using `status`:

    (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 `Example` and `JSON`.

Note

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`. `Pkg` has much more to offer in terms of powerful package management, read the full manual to learn more!

Theme

This document was generated with Documenter.jl version 0.27.23 on Tuesday 14 November 2023. Using Julia version 1.9.4.