dpm (Daml Package Manager)

Command reference and configuration for dpm, the primary CLI tool for Canton development.

dpm is the command-line interface for Canton development. It manages SDK installation, project scaffolding, compilation, testing, code generation, and local development environments. Most Canton development workflows start with a dpm command.

Pre-requisites

Dpm runs on Windows, macOS and Linux. For full functionality, you must have installed:

1. VS Code download
2. JDK 17 or greater, installed and part of your JAVA_HOME. If you do not already have a JDK installed, try OpenJDK or Eclipse Adoptium.
3. If you are on a Mac with Apple Silicon, you may need to install Rosetta 2 to run x86 binaries. You can do this by running the following command in a terminal:

softwareupdate --install-rosetta

Installation

Install dpm usually involves downloading a single binary and adding it to your PATH.

When installing dpm, you can set the DPM_HOME environment variable to change the location where the SDK and any future updates are installed. The default is:

• ${HOME}/.dpm/ on Mac and Linux
• %APPDATA%/.dpm/ on Windows

To install the latest version:

Mac/Linux Installation

curl https://get.digitalasset.com/install/install.sh | sh

Windows Installation

Download and run the windows installer, which will install the dpm sdk and set up the PATH variable for you.

Manual Installation

If you prefer a more manual installation process, see Manual Installation Instructions.

Installing dpm without an SDK

You can download the dpm binary which doesn’t have any SDK bundled with it from the releases page. You can then run dpm install or dpm install package described in the next section.

Verifying the Installation

Once installed, verify the installation:

dpm --version

Command Reference

Project Management

dpm init — Initialize a new Daml project in the current directory. Creates a daml.yaml configuration file and a basic project structure.

You can manage SDK versions manually by using dpm install. To install the SDK version specified in the daml.yaml, run:

dpm install

To install a specific SDK version, for example version 3.4.11, run:

dpm install 3.4.11

To see the active SDK version:

dpm version --active

3.4.11

To list the installed SDK versions, including the currently active one (marked with *):

dpm version

  3.4.10
* 3.4.11

To additionally list all the SDK versions that can be installed, as well as the installed versions:

dpm version --all

To get the list in a machine readable format:

dpm version --all -o json

 [
    {
        "version": "3.4.9",
        "remote": true
    },
    {
        "version": "3.4.10",
        "installed": true,
        "remote": true
    },
    {
        "version": "3.4.11",
        "installed": true,
        "remote": true,
        "active": true
    }
]

dpm init

dpm new — Create a new project from a template. Templates provide working examples that you can modify.

dpm new my-project --template daml-intro-contracts

Building and Testing

dpm build — Compile Daml source files into a DAR (Daml Archive) file. The output goes to .daml/dist/.

dpm build

For multi-package projects, build all sub-packages:

dpm build --all

dpm test — Run all Daml Script tests in the current package. Produces a summary with pass/fail status and coverage report.

dpm test

dpm install — Download and install the Daml SDK version specified in daml.yaml.

dpm install

Code Generation

dpm codegen-js — Generate TypeScript/JavaScript bindings from a compiled DAR file.

dpm codegen-js .daml/dist/my-project.dar -o generated-ts

dpm codegen-java — Generate Java bindings from a compiled DAR file.

dpm codegen-java .daml/dist/my-project.dar -o generated-java

Development Environment

dpm sandbox — Start a local Canton sandbox node. This runs a single-participant Canton instance with an in-memory ledger for testing.

dpm sandbox

dpm studio — Open Daml Studio (the VS Code extension) for the current project. This launches VS Code with the Daml extension activated.

dpm studio

Exploration

Use --help on any command to see available options:

dpm --help
dpm build --help
dpm codegen-java --help
dpm inspect-dar --help

Summary of dpm Commands

• dpm build: Build a Daml package or project

  This builds the Daml project according to the project config file daml.yaml (see configuration files).

  In particular, it will use the dpm SDK (specified in the sdk-version field in daml.yaml) to resolve dependencies and compile the Daml project.

  Given a daml.yaml and .daml source files, the dpm build command will generate a .dar for this package. See How to build Daml Archives for how to define a package and build it to a DAR.

• dpm test: Test the current Daml project or the given files by running all test declarations.

  This runs all daml scripts defined within a package.

  Daml Scripts are top level values of type Script (), from the daml-script package. This package mimics a Canton Ledger Client for quick iterative testing, and direct support within Daml Studio. The command runs these scripts against a reference Ledger called the IDE Ledger, which implements the core functionality of the Canton Ledger without the complexity of multi-participant setups.

  It is most useful for verifying the fundamentals of your ledger model, before moving onto integration testing via the Ledger API directly, or the Daml Codegen. dpm test also provides code coverage information for templates and choices used.

• dpm clean: Clean a Daml package or project

  This removes any Daml artifact files created in your package during a daml build, including DARs.

• dpm add: Add components and dars to project

• dpm update: Update components and dars in project

• dpm codegen-java: Daml to Java compiler

• dpm codegen-js: Daml to JavaScript compiler

• dpm canton-console: Canton console client

• dpm daml-shell: Daml-shell client for PQS

• dpm damlc: Compiler and IDE backend for the Daml programming language

• dpm docs: Generate documentation for a daml package from its documentation comments

• dpm init: Initialize a daml.yaml project configuration file in the current directory

• dpm install: Install project’s dependencies or specific dpm-sdk version

• dpm install package: Install the SDK(s), components and dars used by current project

• dpm inspect-dar: Inspect a DAR archive

• dpm new: Create a new Daml package

• dpm publish: Commands for publishing artifacts

• dpm pqs: Participant query store

• dpm sandbox: Run full Canton installation in a single process

• dpm script: Daml Script Binary

• dpm studio: Launch Daml Studio

• dpm upgrade-check: Check upgrade validity between package versions

To specify additional options for sandbox/navigator/the HTTP JSON API you can use --sandbox-option=opt, --navigator-option=opt and --json-api-option=opt.

• dpm validate-dar Validate a DAR archive

  Note that you need to update your project config file to use the new version.

Configuration Files

daml.yaml

Every Daml project has a daml.yaml file at its root. If a daml.yaml file doesn’t exist in your project, you can create one with:

dpm init

It specifies the SDK version, project metadata, source directory, and dependencies.

sdk-version: 3.4.0
name: my-project
source: daml
version: 1.0.0
dependencies:
  - daml-prim
  - daml-stdlib
build-options:
  - --target=3.4

Key fields:

• sdk-version — The Daml SDK version to use. dpm install downloads this version.
• name — The package name, used in the output DAR filename
• source — Directory containing Daml source files (typically daml)
• dependencies — List of Daml library dependencies
• build-options — Compiler flags (e.g., target LF version)

multi-package.yaml

For projects with multiple Daml packages, a multi-package.yaml at the project root lists all sub-packages:

packages:
  - ./contracts
  - ./tests
  - ./scripts

Running dpm build --all from the root builds all listed packages in dependency order.

dpm-config.yaml

The dpm-config.yaml file stores global dpm configuration such as SDK installation paths and registry settings. It is typically located in your home directory and rarely needs manual editing.

dpm Global configuration (dpm-config.yaml)

Global configuration is stored at ${DPM_HOME}/dpm-config.yaml and is optional. It can be used for purposes such as:

• Registry URL — Override the default OCI registry for SDK components.
• Authentication — Point to registry credentials.
• Insecure registry — Allow HTTP connections to a registry.

Variable interpolation

Both daml.yaml and dpm-config.yaml support variable interpolation, which lets you avoid hardcoded values (such as registry URLs or credentials paths) and reference environment variables or other dynamic values.

daml assistant to dpm migration steps

This section provides a step-by-step guide for projects originally built with the Daml assistant.

Migration steps

1. Install Dpm

   Follow the installation instructions above.

2. Verify Dpm is in your PATH

dpm version

3. Remove ~/.daml/bin from your PATH

   Edit your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, ~/.profile) and remove any line that adds ~/.daml/bin to your PATH

4. Remove the Daml assistant

rm -rf ~/.daml

5. Create a project configuration if needed

   If a daml.yaml file doesn’t already exist in your project, generate one:

dpm init

6. Replace daml commands with dpm

   Most commands map directly. See the command migration table below.

   Six daml commands have been removed and replaced with Declarative API, Canton Console, JSON API, and/or gRPC API calls. See removed command replacements for full details.

7. Review project configuration

   Review your daml.yaml to ensure it is compatible with dpm. Audit parent directories for stale daml.yaml files. Delete orphan or invalid files.

8. Review global configuration (optional)

   Review or create ${DPM_HOME}/dpm-config.yaml if you need to customize registry, authentication, or other global settings.

9. Set up variable interpolation (optional)

   Use variable interpolation in your configuration files to avoid hardcoded values.

10. Update CI/CD pipelines (if applicable)

    Update any CI/CD pipeline scripts that reference daml commands to use the corresponding dpm commands instead.

Command migration table

daml command	dpm command	purpose
daml new	dpm new	Create a new Daml project
daml build	dpm build	Compile the Daml project
daml test	dpm test	Run tests for the Daml project
daml install	dpm install	Install Daml SDK components
daml codegen java	dpm codegen-java	Java code generation
daml codegen js	dpm codegen-js	TypeScript code generation
daml damlc	dpm damlc	Invoke the daml compiler
daml studio	dpm studio	Open project in Visual Studio
daml sandbox	dpm sandbox	Launch a Daml Sandbox
daml ledger allocate-parties_	Use Declarative API – OR – JSON / gRPC API	Allocate parties on a ledger
daml ledger list-parties_	JSON / gRPC API	list parties on a ledger
daml ledger upload-dar_	Use Declarative API – OR – JSON / gRPC API	Upload (and vet) dars on a ledger
daml ledger fetch-dar_	gRPC API	Fetch a Dar from a ledger.
daml packages_	JSON / gRPC API	Package a Daml project
daml start_	dpm sandbox dpm build Use Declarative API – OR – JSON / gRPC to upload/allocate	Start a local Daml Ledger

Removed command replacements

The following daml commands have no direct dpm equivalent. Use the Declarative API, Canton Console, JSON API, or gRPC API instead.

daml ledger allocate-parties

Method	Details
Declarative API	canton.parameters.enable-alpha-state-via-config = yes with canton.participants.sandbox.alpha-dynamic { parties = [{ party = "Alice", synchronizers = ["mysync"] }, { party = "Bob" }] }
Canton Console	ledger_api.parties.allocate(...)
JSON API	POST /v2/parties/
gRPC	PartyManagementService.AllocateParty

daml ledger list-parties

Method	Details
Canton Console	ledger_api.parties.list()
JSON API	GET /v2/parties or GET /v2/parties/{party}
gRPC	PartyManagementService.ListKnownParties

daml ledger upload-dar

Method	Details
Declarative API	canton.parameters.enable-alpha-state-via-config = yes with canton.participants.sandbox.alpha-dynamic.dars = [{ location = "./my-asset.dar" }, { location = "https://path.to/repo/token.dar", request-headers = { AuthenticationToken : "mytoken" } }]
Canton Console	ledger_api.packages.upload_dar(...)
JSON API	POST /v2/dars/
gRPC	PackageManagementService.UploadDarFile

daml ledger fetch-dar

Method	Details
JSON API	GET /v2/packages/{package-id}
gRPC	PackageService.GetPackage

daml packages

Method	Details
Canton Console	ledger_api.packages.list()
JSON API	GET /v2/packages or GET /v2/packages/{package-id}/status
gRPC	PackageService.ListPackages

daml start

Replace with dpm sandbox combined with dpm build. Use the Declarative API or JSON/gRPC API to upload DARs and allocate parties as needed.

See dpm sandbox for details on running a local Canton installation.

Publishing Components

This functionality is available in DPM version 1.0.14 or later (or bundled with SDK 3.5 or later)

To share or use your Component in various projects, you can publish it to a repository.

dpm publish component oci://<destination>:<strict semantic version> \
    --platform generic="/path/to/component/directory"

for example:

dpm publish component oci://example.com/my/components/foo:1.0.0 \
    --platform generic="~/component-foo"

This will publish version 1.0.0 of foo as OCI to example.com/my/components/foo:1.0.0

For multi-platform components, you can instead provide a directory for each platform. For example:

dpm publish component oci://example.com/my/components/foo:1.0.0 \
    --platform linux/arm64="/some/directory" \
    --platform windows/amd64="/another/directory"

See the dpm publish component --help command for more available options.

Also, you can view the published versions (and tags) of a component

dpm tags oci://example.com/my/components/foo

For information on how to use the published component in your project, see the section on using components

Publishing Dars to an OCI Repository

This functionality is available in DPM version 1.0.20 or later (or bundled with SDK 3.5.2 or later).

Similarly to components, you can publish dars to an OCI repository for distribution:

dpm publish dar oci://example.com/my/dars/foo:1.0.0 \
    -f ./foo.dar \
    --extra-tags devnet    # optional

You should now be able to see the published version via dpm tags see the Listing tags docs section.

See the Remote Dars docs section to learn how to install oci:// dars in your project.

Typical Workflow

A common development cycle with dpm:

# 1. Set up the project
dpm new my-app --template daml-intro-contracts
cd my-app
dpm install

# 2. Write Daml code, then compile
dpm build

# 3. Run tests
dpm test

# 4. Start a local sandbox for integration testing
dpm sandbox

# 5. Generate bindings for your backend
dpm codegen-java .daml/dist/my-app.dar -o generated-java
dpm codegen-js .daml/dist/my-app.dar -o generated-ts

Listing available tags and versions in an OCI repository

You can use the dpm tags command to view published versions and tags for a specific component or dar.

dpm tags oci://example.com/my/dars/my-package
1.0.0
1.2.3
latest

Related Pages

• Daml SDK — What the SDK includes and how versions work
• Sandbox — Local testing environment started by dpm sandbox
• Daml Studio — VS Code extension launched by dpm studio
• Daml Script — Writing and running tests with dpm test

Mac/Linux Installation

If you cannot / wish not to use the shell script to install for Linux or OSX, you can alternatively install dpm manually by running this set of commands in your terminal:

The latest stable release version can be found by hitting the following URL:

VERSION="$(curl -sS "https://get.digitalasset.com/install/latest")"

And you can then use this to retrieve the tarball of the full installation, extract, and install, as outlined in the full instructions below.

#! /usr/bin/env bash
set -xeuo pipefail

# get latest version number
VERSION="$(curl -sS "https://get.digitalasset.com/install/latest")"

# set your architecture to either amd64 | arm64
ARCH="$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')"

# set your OS to either darwin or linux
OS="$(uname | tr '[:upper:]' '[:lower:]')"

# pull down appropriate tarball for your OS and architecture
readonly TARBALL="dpm-${VERSION}-${OS}-${ARCH}.tar.gz"

# determine location of tarball to download
TARBALL_URL="https://get.digitalasset.com/install/dpm-sdk/${TARBALL}"

# make tmpdir
TMPDIR="$(mktemp -d)"

# download tarball
curl -SLf "${TARBALL_URL}" --output "${TMPDIR}/${TARBALL}" --progress-bar "$@"

# create directory to extract into
extracted="${TMPDIR}/extracted"
mkdir -p "${extracted}"

# untar to extracted directory
tar xzf "${TMPDIR}/${TARBALL}" -C "${extracted}" --strip-components 1

# bootstrap dpm
"${extracted}/bin/dpm" bootstrap "${extracted}"

# verify dpm version runs and does not return an error
if ! "${extracted}/bin/dpm" version; then
  echo "dpm version failed" >&2
  exit 1
fi

# cleanup tmpdir
rm -rf "${TMPDIR}"

Windows Installation

Download and unpack the windows dpm-sdk archive (.zip), then:

# Extract the downloaded zip ($ZIP_PATH) to temp directory ($EXTRACTED)
# Avoid using the system's temp directory as the user may not have rights to it
New-Item -ItemType Directory -Path $EXTRACTED | Out-Null
Expand-Archive -Path $ZIP_PATH -DestinationPath $EXTRACTED

# Optionally, override the TMP and DPM_HOME environment variable to point to directories other than the default,
# as the user might not have rights to the default directories.
# (You might also want to persist these variables as DPM uses them on every invocation)
$env:TMP = "<user-owned temporary directory>"
$env:DPM_HOME = "<user-owned directory>"

& "$EXTRACTED\windows-amd64\bin\dpm.exe" bootstrap $EXTRACTED\windows-amd64

Unstable Version Manual Installation

Preview / unstable versions are also available for experimentation, though it is always recommended to use the stable versions listed above instead.

Unstable Mac / Linux

Follow the dpm-manual-installation-mac-linux instructions to install an unstable version, but note the differences in VERSION and TARBALL_URL.

The latest unstable release version can be found by hitting the following URL:

VERSION="$(curl -sS "https://get.digitalasset.com/unstable/install/latest")"

The unstable tarball can be retrieved from the following URL:

# determine location of tarball to download
TARBALL_URL="https://get.digitalasset.com/unstable/install/dpm-sdk/${TARBALL}"

Unstable Windows

Download and unpack the latest windows unstable dpm-sdk archive (.zip), then follow dpm-manual-installation-windows instructions.