Module Dependencies

A module reference follows the format: [proto://]host/repo[/subpath][@version], where:

host is the domain name of the Git hosting service, e.g. github.com.
repo is the repository path, typically in the format owner/name.
proto:// is optional and can be either ssh:// or https:// if you want to be explicit about the protocol. If omitted, Dagger will automatically choose the protocol based on available authentication methods.
/subpath is optional and specifies a subdirectory within the repository, useful for monorepos.
@version can be a tag, branch, or commit. If omitted, the default branch is used.

For example, in the reference github.com/shykes/daggerverse/hello@v0.3.0:

github.com is the host
shykes/daggerverse is the repository
hello is the subpath within the repository
v0.3.0 is the version tag

The .git extension for the repository is optional for HTTP refs or explicit SSH refs, except for GitLab, when referencing modules stored on a private repo or private subgroup.

Installation

You can call Dagger Functions from any other Dagger module in your own Dagger module simply by adding it as a module dependency with dagger install, as in the following example:

dagger install github.com/shykes/daggerverse/hello@v0.3.0

This module will be added to your dagger.json:

...
"dependencies": [
  {
    "name": "hello",
    "source": "github.com/shykes/daggerverse/hello@54d86c6002d954167796e41886a47c47d95a626d"
  }
]

When you add a dependency to your module with dagger install, the dependent module will be added to the code-generation routines and can be accessed from your own module's code.

The entrypoint to accessing dependent modules from your own module's code is dag, the Dagger client, which is pre-initialized. It contains all the core types (like Container, Directory, etc.), as well as bindings to any dependencies your module has declared.

Here is an example of accessing the installed hello module from your own module's code:

Go
Python
TypeScript
PHP
Java

func (m *MyModule) Greeting(ctx context.Context) (string, error) {
  return dag.Hello().Hello(ctx)
}

@function
async def greeting(self) -> str:
  return await dag.hello().hello()

@func()
async greeting(): Promise<string> {
  return await dag.hello().hello()
}

#[DaggerFunction]
public function greeting(): string
{
    return dag()->hello()->hello();
}

@Function
public String greeting() throws ExecutionException, DaggerQueryException, InterruptedException {
    return dag().hello().hello();
}

Here is a more complex example. It is a Dagger Function that utilizes a module from the Daggerverse to build a Go project, then chains a Dagger API method to open an interactive terminal session in the build directory.

First, install the module:

dagger install github.com/kpenfound/dagger-modules/golang@v0.2.0

Next, create a new Dagger Function:

Go
Python
TypeScript
PHP
Java

package main

import (
	"dagger/my-module/internal/dagger"
)

type MyModule struct{}

func (m *MyModule) Example(buildSrc *dagger.Directory, buildArgs []string) *dagger.Directory {
	return dag.
		Golang().
		Build(buildArgs, dagger.GolangBuildOpts{Source: buildSrc}).
		Terminal()
}

import dagger
from dagger import dag, function, object_type


@object_type
class MyModule:
    @function
    def example(
        self, build_src: dagger.Directory, build_args: list[str]
    ) -> dagger.Directory:
        return dag.golang().build(source=build_src, args=build_args).terminal()

import { dag, Directory, object, func } from "@dagger.io/dagger"

@object()
class MyModule {
  @func()
  example(buildSrc: Directory, buildArgs: string[]): Directory {
    return dag.golang().build({ source: buildSrc, args: buildArgs }).terminal()
  }
}

<?php

declare(strict_types=1);

namespace DaggerModule;

use Dagger\Attribute\{DaggerObject, DaggerFunction, ListOfType};
use Dagger\Directory;

use function Dagger\dag;

#[DaggerObject]
class MyModule
{
    #[DaggerFunction]
    public function example(
        Directory $buildSrc,
        #[ListOfType('string')]
        array $buildArgs,
    ): Directory {
        return dag()
            ->golang()
            ->build(source: $buildSrc, args: $buildArgs)
            ->terminal();
    }
}

package io.dagger.modules.mymodule;

import static io.dagger.client.Dagger.dag;

import io.dagger.client.Directory;
import io.dagger.client.Golang;
import io.dagger.module.annotation.Function;
import io.dagger.module.annotation.Object;
import java.util.List;

@Object
public class MyModule {
  @Function
  public Directory example(Directory buildSrc, List<String> buildArgs) {
    return dag()
        .golang()
        .build(buildArgs, new Golang.BuildArguments().withSource(buildSrc))
        .terminal();
  }
}

This Dagger Function accepts two arguments - the source directory and a list of build arguments - and does the following:

It invokes the Golang module via the dag Dagger client.
It calls a Dagger Function from the module to build the source code and return a just-in-time directory with the compiled binary.
It chains a core Dagger API method to open an interactive terminal session in the returned directory.

Here is an example call for this Dagger Function:

System shell
Dagger Shell
Dagger CLI

dagger -c 'example https://github.com/golang/example#master:/hello .'

First type 'dagger' for interactive mode.
example https://github.com/golang/example#master:/hello .

dagger call example --build-src=https://github.com/golang/example#master:/hello --build-args=.

You can also use local modules as dependencies, as long as they are in the same git repository. For example:

dagger install ./path/to/module

note

Installing a module using a local path (relative or absolute) is only possible if your module is within the repository root (for Git repositories) or the directory containing the dagger.json file (for all other cases).

Private modules

You can also install private modules from remote repositories, as long as you have access to them. Dagger supports authentication via both HTTPS (using Git credential managers) and SSH (using SSH_AUTH_SOCK). For more information, see the documentation on remote repositories.

When installing a private module, you can use either the normal ref style (preferred if possible, since it allows any available authentication method to be used), or explicitly specify the protocol. For example, the following commands all install the same private module:

dagger install github.com/username/private-repo/module
dagger install https://github.com/username/private-repo/module
dagger install ssh://git@github.com/username/private-repo/module

Uninstallation

To remove a dependency from your Dagger module, use the dagger uninstall command. The dagger uninstall command can be passed either a remote repository reference or a local module name.

The commands below are equivalent:

dagger uninstall hello
dagger uninstall github.com/shykes/daggerverse/hello

Update

To update a dependency in your Dagger module to the latest version (or the version specified), use the dagger update command. The target module must be local.

The commands below are equivalent:

dagger update hello
dagger update github.com/shykes/daggerverse/hello

note

Given a dependency like github.com/path/name@branch/tag:

dagger update github.com/path/name updates the dependency to the latest commit of the branch/tag.
dagger update github.com/path/name@version updates the dependency to the latest commit for the version branch/tag.

Installation​

Private modules​

Uninstallation​

Update​

Installation

Private modules

Uninstallation

Update