Pkg

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

What follows is a quick overview of Pkg, Julia's package manager. It should help new users become familiar with basic Pkg features.

Pkg comes with a REPL. Enter the Pkg REPL by pressing ] from the Julia REPL. To get back to the Julia REPL, press backspace or ^C.

Upon entering the Pkg REPL, you should see a similar prompt:

(v1.1) pkg>

To add a package, use add:

(v1.1) pkg> add Example

We can also specify multiple packages at once:

(v1.1) pkg> add JSON StaticArrays

To remove packages, use rm:

(v1.1) pkg> rm JSON StaticArrays

So far, we have referred only to registered packages. Pkg also supports working with unregistered packages. To add an unregistered package, specify a URL:

(v1.1) pkg> add https://github.com/JuliaLang/Example.jl

Use rm to remove this package by name:

(v1.1) pkg> rm Example

Use update to update an installed package:

(v1.1) pkg> update Example

To update all installed packages, use update without any arguments:

(v1.1) pkg> update

Up to this point, we have covered basic package management: adding, updating and removing packages. This will be familiar if you have used other package managers. Pkg offers significant advantages over traditional package managers by organizing dependencies into environments.

You may have noticed the (v1.1) in the REPL prompt. This lets us know v1.1 is the active 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.1) pkg> activate tutorial
[ Info: activating new environment at `/tmp/tutorial/Project.toml`.

Pkg lets us know we are creating a new environment and that this environment will be stored in the /tmp/tutorial directory.

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 `/tmp/tutorial/Project.toml`
   (empty environment)

/tmp/tutorial/Project.toml is the location of the active environment's project file. A project file is where Pkg stores metadata for an environment. Notice this new environment is empty. Let us add a package and observe:

(tutorial) pkg> add Example
...

(tutorial) pkg> status
    Status `/tmp/tutorial/Project.toml`
  [7876af07] Example v0.5.1

We can see tutorial now contains Example as a dependency.

Say we are working on Example and feel it needs new functionality. How can we modify the source code? We can use develop to set up a git clone of the Example package.

(tutorial) pkg> develop --local Example
...

(tutorial) pkg> status
    Status `/tmp/tutorial/Project.toml`
  [7876af07] Example v0.5.1+ [`dev/Example`]

Notice the feedback has changed. dev/Example refers to the location of the newly created clone. If we look inside the /tmp/tutorial directory, we will notice the following files:

tutorial
├── dev
│   └── Example
├── Manifest.toml
└── Project.toml

Instead of loading a registered version of Example, Julia will load the source code contained in tutorial/dev/Example.

Let's try it out. First we modify the file at tutorial/dev/Example/src/Example.jl and add a simple function:

plusone(x::Int) = x + 1

Now we can go back to the Julia REPL and load the package:

julia> import Example

Julia should load our new code. Let's test it:

julia> Example.plusone(1)
2

Say we have a change of heart and decide the world is not ready for such elegant code. We can tell Pkg to stop using the local clone and use a registered version instead. We do this with free:

(tutorial) pkg> free Example

When you are done experimenting with tutorial, you can return to the default environment by running activate with no arguments:

(tutorial) pkg> activate

(v1.1) pkg>

If you are ever stuck, you can ask Pkg for help:

(v1.1) 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.1) 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!