General usage

dub [--version] [<command>] [<options...>] [-- [<application arguments...>]]

If the command is omitted, DUB will default to "run". When running an application, "--" can be used to separate DUB options from options passed to the application.

Setting the "http_proxy" environment variable will instruct DUB to use a proxy server when fetching packages or package meta data.

The following options are always accepted in addition to command specific ones:

-h--help Display general or command specific help
 --root=<value> Path to operate in instead of the current working dir
 --registry=<value> Search the given DUB registry URL first when resolving dependencies. Can be specified multiple times.
 --skip-registry=<value> Skips searching certain package registries for dependencies:
    none: Search all configured registries (default)
    standard: Don't search on http://code.dlang.org/
    all: Search none of the configured registries
 --annotate Do not perform any action, just print what would be done
 --bare Read only packages contained in the current directory
-v--verbose Print diagnostic output
 --vverbose Print debug output
-q--quiet Only print warnings and errors
 --vquiet Print no messages
 --cache=<value> Puts any fetched packages in the specified location [local|system|user].

Command overview

Package creation commands

init

dub init [<directory> [<dependency>...]] [<options...>]

Initializes an empty package of the specified type in the given directory. By default, the current working dirctory is used.

Available options:

-t--type=<value> Set the type of project to generate. Available types:

minimal - simple "hello world" project (default)
vibe.d - minimal HTTP server based on vibe.d
deimos - skeleton for C header bindings
-f--format=<value> Sets the format to use for the package description file. Possible values:
    json (default), sdl
-n--non-interactive Don't enter interactive mode.

Build, test and run commands

run

dub run [<package>] [<options...>] -- <application arguments>

Builds and runs a package (uses the main package in the current working directory by default)

Available options:

 --temp-build Builds the project in the temp folder if possible.
 --rdmd Use rdmd instead of directly invoking the compiler
-f--force Forces a recompilation even if the target is up to date
-b--build=<value> Specifies the type of build to perform. Note that setting the DFLAGS environment variable will override the build type with custom flags.
Possible names:
    debug (default), plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, unittest-cov and custom types
-c--config=<value> Builds the specified configuration. Configurations can be defined in dub.json
 --override-config=<value> Uses the specified configuration for a certain dependency. Can be specified multiple times.
Format: --override-config=<dependency>/<config>
 --compiler=<value> Specifies the compiler binary to use (can be a path).
Arbitrary pre- and suffixes to the identifiers below are recognized (e.g. ldc2 or dmd-2.063) and matched to the proper compiler type:
    dmd, gdc, ldc, gdmd, ldmd
-a--arch=<value> Force a different architecture (e.g. x86 or x86_64)
-d--debug=<value> Define the specified debug version identifier when building - can be used multiple times
 --nodeps Do not check/update dependencies before building
 --build-mode=<value> Specifies the way the compiler and linker are invoked. Valid values:
    separate (default), allAtOnce, singleFile
 --single Treats the package name as a filename. The file must contain a package recipe comment.
 --force-remove Deprecated option that does nothing.
 --combined Tries to build the whole project in a single compiler run.
 --print-builds Prints the list of available build types
 --print-configs Prints the list of available configurations
 --print-platform Prints the identifiers for the current build platform as used for the build fields in dub.json
 --parallel Runs multiple compiler instances in parallel, if possible.

build

dub build [<package>] [<options...>]

Builds a package (uses the main package in the current working directory by default)

Available options:

 --rdmd Use rdmd instead of directly invoking the compiler
-f--force Forces a recompilation even if the target is up to date
-b--build=<value> Specifies the type of build to perform. Note that setting the DFLAGS environment variable will override the build type with custom flags.
Possible names:
    debug (default), plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, unittest-cov and custom types
-c--config=<value> Builds the specified configuration. Configurations can be defined in dub.json
 --override-config=<value> Uses the specified configuration for a certain dependency. Can be specified multiple times.
Format: --override-config=<dependency>/<config>
 --compiler=<value> Specifies the compiler binary to use (can be a path).
Arbitrary pre- and suffixes to the identifiers below are recognized (e.g. ldc2 or dmd-2.063) and matched to the proper compiler type:
    dmd, gdc, ldc, gdmd, ldmd
-a--arch=<value> Force a different architecture (e.g. x86 or x86_64)
-d--debug=<value> Define the specified debug version identifier when building - can be used multiple times
 --nodeps Do not check/update dependencies before building
 --build-mode=<value> Specifies the way the compiler and linker are invoked. Valid values:
    separate (default), allAtOnce, singleFile
 --single Treats the package name as a filename. The file must contain a package recipe comment.
 --force-remove Deprecated option that does nothing.
 --combined Tries to build the whole project in a single compiler run.
 --print-builds Prints the list of available build types
 --print-configs Prints the list of available configurations
 --print-platform Prints the identifiers for the current build platform as used for the build fields in dub.json
 --parallel Runs multiple compiler instances in parallel, if possible.

test

dub test [<package>] [<options...>] -- <application arguments>

Builds the package and executes all contained unit tests.

If no explicit configuration is given, an existing "unittest" configuration will be preferred for testing. If none exists, the first library type configuration will be used, and if that doesn't exist either, the first executable configuration is chosen.

When a custom main file (--main-file) is specified, only library configurations can be used. Otherwise, depending on the type of the selected configuration, either an existing main file will be used (and needs to be properly adjusted to just run the unit tests for 'version(unittest)'), or DUB will generate one for library type configurations.

Finally, if the package contains a dependency to the "tested" package, the automatically generated main file will use it to run the unit tests.

Available options:

 --main-file=<value> Specifies a custom file containing the main() function to use for running the tests.
 --combined Tries to build the whole project in a single compiler run.
-f--force Forces a recompilation even if the target is up to date
 --coverage Enables code coverage statistics to be generated.
-b--build=<value> Specifies the type of build to perform. Note that setting the DFLAGS environment variable will override the build type with custom flags.
Possible names:
    debug (default), plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, unittest-cov and custom types
-c--config=<value> Builds the specified configuration. Configurations can be defined in dub.json
 --override-config=<value> Uses the specified configuration for a certain dependency. Can be specified multiple times.
Format: --override-config=<dependency>/<config>
 --compiler=<value> Specifies the compiler binary to use (can be a path).
Arbitrary pre- and suffixes to the identifiers below are recognized (e.g. ldc2 or dmd-2.063) and matched to the proper compiler type:
    dmd, gdc, ldc, gdmd, ldmd
-a--arch=<value> Force a different architecture (e.g. x86 or x86_64)
-d--debug=<value> Define the specified debug version identifier when building - can be used multiple times
 --nodeps Do not check/update dependencies before building
 --build-mode=<value> Specifies the way the compiler and linker are invoked. Valid values:
    separate (default), allAtOnce, singleFile
 --single Treats the package name as a filename. The file must contain a package recipe comment.
 --force-remove Deprecated option that does nothing.

generate

dub generate <generator> [<package>] [<options...>]

Generates project files using one of the supported generators:

visuald - VisualD project files
sublimetext - SublimeText project file
cmake - CMake build scripts
build - Builds the package directly

An optional package name can be given to generate a different package than the root/CWD package.

Available options:

-b--build=<value> Specifies the type of build to perform. Note that setting the DFLAGS environment variable will override the build type with custom flags.
Possible names:
    debug (default), plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, unittest-cov and custom types
-c--config=<value> Builds the specified configuration. Configurations can be defined in dub.json
 --override-config=<value> Uses the specified configuration for a certain dependency. Can be specified multiple times.
Format: --override-config=<dependency>/<config>
 --compiler=<value> Specifies the compiler binary to use (can be a path).
Arbitrary pre- and suffixes to the identifiers below are recognized (e.g. ldc2 or dmd-2.063) and matched to the proper compiler type:
    dmd, gdc, ldc, gdmd, ldmd
-a--arch=<value> Force a different architecture (e.g. x86 or x86_64)
-d--debug=<value> Define the specified debug version identifier when building - can be used multiple times
 --nodeps Do not check/update dependencies before building
 --build-mode=<value> Specifies the way the compiler and linker are invoked. Valid values:
    separate (default), allAtOnce, singleFile
 --single Treats the package name as a filename. The file must contain a package recipe comment.
 --force-remove Deprecated option that does nothing.
 --combined Tries to build the whole project in a single compiler run.
 --print-builds Prints the list of available build types
 --print-configs Prints the list of available configurations
 --print-platform Prints the identifiers for the current build platform as used for the build fields in dub.json
 --parallel Runs multiple compiler instances in parallel, if possible.

describe

dub describe [<package>] [<options...>]

Prints a JSON build description for the root package an all of their dependencies in a format similar to a JSON package description file. This is useful mostly for IDEs.

All usual options that are also used for build/run/generate apply.

When --data=VALUE is supplied, specific build settings for a project will be printed instead (by default, formatted for the current compiler).

The --data=VALUE option can be specified multiple times to retrieve several pieces of information at once. A comma-separated list is also acceptable (ex: --data=dflags,libs). The data will be output in the same order requested on the command line.

The accepted values for --data=VALUE are:

main-source-file, dflags, lflags, libs, linker-files, source-files, versions, debug-versions, import-paths, string-import-paths, import-files, options

The following are also accepted by --data if --data-list is used:

target-type, target-path, target-name, working-directory, copy-files, string-import-files, pre-generate-commands, post-generate-commands, pre-build-commands, post-build-commands, requirements

Available options:

-b--build=<value> Specifies the type of build to perform. Note that setting the DFLAGS environment variable will override the build type with custom flags.
Possible names:
    debug (default), plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, unittest-cov and custom types
-c--config=<value> Builds the specified configuration. Configurations can be defined in dub.json
 --override-config=<value> Uses the specified configuration for a certain dependency. Can be specified multiple times.
Format: --override-config=<dependency>/<config>
 --compiler=<value> Specifies the compiler binary to use (can be a path).
Arbitrary pre- and suffixes to the identifiers below are recognized (e.g. ldc2 or dmd-2.063) and matched to the proper compiler type:
    dmd, gdc, ldc, gdmd, ldmd
-a--arch=<value> Force a different architecture (e.g. x86 or x86_64)
-d--debug=<value> Define the specified debug version identifier when building - can be used multiple times
 --nodeps Do not check/update dependencies before building
 --build-mode=<value> Specifies the way the compiler and linker are invoked. Valid values:
    separate (default), allAtOnce, singleFile
 --single Treats the package name as a filename. The file must contain a package recipe comment.
 --force-remove Deprecated option that does nothing.
 --import-paths Shortcut for --data=import-paths --data-list
 --string-import-paths Shortcut for --data=string-import-paths --data-list
 --data=<value> Just list the values of a particular build setting, either for this package alone or recursively including all dependencies. Accepts a comma-separated list. See above for more details and accepted possibilities for VALUE.
 --data-list Output --data information in list format (line-by-line), instead of formatting for a compiler command line.
 --data-0 Output --data information using null-delimiters, rather than spaces or newlines. Result is usable with, ex., xargs -0.

clean

dub clean [<package>] [<options...>]

This command removes any cached build files of the given package(s). The final target file, as well as any copyFiles are currently not removed.
Without arguments, the package in the current working directory will be cleaned.

Available options:

 --all-packages Cleans up *all* known packages (dub list)

dustmite

dub dustmite <destination-path> [<options...>] -- <application arguments>

This command uses the Dustmite utility to isolate the cause of build errors in a DUB project.

It will create a copy of all involved packages and run dustmite on this copy, leaving a reduced test case.

Determining the desired error condition is done by checking the compiler/linker status code, as well as their output (stdout and stderr combined). If --program-status or --program-regex is given and the generated binary is an executable, it will be executed and its output will also be incorporated into the final decision.

Available options:

 --compiler-status=<value> The expected status code of the compiler run
 --compiler-regex=<value> A regular expression used to match against the compiler output
 --linker-status=<value> The expected status code of the linker run
 --linker-regex=<value> A regular expression used to match against the linker output
 --program-status=<value> The expected status code of the built executable
 --program-regex=<value> A regular expression used to match against the program output
 --test-package=<value> Perform a test run - usually only used internally
 --combined Builds multiple packages with one compiler run
-b--build=<value> Specifies the type of build to perform. Note that setting the DFLAGS environment variable will override the build type with custom flags.
Possible names:
    debug (default), plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, unittest-cov and custom types
-c--config=<value> Builds the specified configuration. Configurations can be defined in dub.json
 --override-config=<value> Uses the specified configuration for a certain dependency. Can be specified multiple times.
Format: --override-config=<dependency>/<config>
 --compiler=<value> Specifies the compiler binary to use (can be a path).
Arbitrary pre- and suffixes to the identifiers below are recognized (e.g. ldc2 or dmd-2.063) and matched to the proper compiler type:
    dmd, gdc, ldc, gdmd, ldmd
-a--arch=<value> Force a different architecture (e.g. x86 or x86_64)
-d--debug=<value> Define the specified debug version identifier when building - can be used multiple times
 --nodeps Do not check/update dependencies before building
 --build-mode=<value> Specifies the way the compiler and linker are invoked. Valid values:
    separate (default), allAtOnce, singleFile
 --single Treats the package name as a filename. The file must contain a package recipe comment.
 --force-remove Deprecated option that does nothing.

Package management commands

fetch

dub fetch <name> [<options...>]

Note: Use the "dependencies" field in the package description file (e.g. dub.json) if you just want to use a certain package as a dependency, you don't have to explicitly fetch packages.

Explicit retrieval/removal of packages is only needed when you want to put packages to a place where several applications can share these. If you just have an dependency to a package, just add it to your dub.json, dub will do the rest for you.

Without specified options, placement/removal will default to a user wide shared location.

Complete applications can be retrieved and run easily by e.g.
$ dub fetch vibelog --local
$ cd vibelog
$ dub

This will grab all needed dependencies and compile and run the application.

Note: DUB does not do a system installation of packages. Packages are instead only registered within DUB's internal ecosystem. Generation of native system packages/installers may be added later as a separate feature.

Available options:

 --version=<value> Use the specified version/branch instead of the latest available match
The remove command also accepts "*" here as a wildcard to remove all versions of the package from the specified location
 --force-remove Deprecated option that does nothing

remove

dub remove <name> [<options...>]

Removes a package that is cached on the local system.

Available options:

 --version=<value> Use the specified version/branch instead of the latest available match
The remove command also accepts "*" here as a wildcard to remove all versions of the package from the specified location
 --force-remove Deprecated option that does nothing
-n--non-interactive Don't enter interactive mode.

upgrade

dub upgrade [<packages...>] [<options...>]

Upgrades all dependencies of the package by querying the package registry(ies) for new versions.

This will update the versions stored in the selections file (dub.selections.json) accordingly.

If one or more package names are specified, only those dependencies will be upgraded. Otherwise all direct and indirect dependencies of the root package will get upgraded.

Available options:

 --prerelease Uses the latest pre-release version, even if release versions are available
 --verify Updates the project and performs a build. If successful, rewrites the selected versions file <to be implemented>.
 --missing-only Performs an upgrade only for dependencies that don't yet have a version selected. This is also done automatically before each build.
 --force-remove Deprecated option that does nothing.

add-path

dub add-path <path> [<options...>]

Adds a default package search path. All direct sub folders of this path will be searched for package descriptions and will be made available as packages. Using this command has the equivalent effect as calling 'dub add-local' on each of the sub folders manually.

Any packages registered using add-path will be preferred over packages downloaded from the package registry when searching for dependencies during a build operation.

The version of the packages will be determined by one of the following:
    - For GIT working copies, the last tag (git describe) is used to determine the version
    - If the package contains a "version" field in the package description, this is used
    - If neither of those apply, "~master" is assumed

Available options:

 --system Register system-wide instead of user-wide

remove-path

dub remove-path <path> [<options...>]

Removes a package search path previously added with add-path.

Available options:

 --system Register system-wide instead of user-wide

add-local

dub add-local <path> [<version>] [<options...>]

Adds a local package directory to be used during dependency resolution. This command is useful for registering local packages, such as GIT working copies, that are either not available in the package registry, or are supposed to be overwritten.

The version of the package is either determined automatically (see the "add-path" command, or can be explicitly overwritten by passing a version on the command line.

See 'dub add-path -h' for a way to register multiple local packages at once.

Available options:

 --system Register system-wide instead of user-wide

remove-local

dub remove-local <path> [<options...>]

Removes a local package directory

Available options:

 --system Register system-wide instead of user-wide

list

dub list  [<options...>]

Prints a list of all local packages. This includes all cached packages (user or system wide), all packages in the package search paths ("dub add-path") and all manually registered packages ("dub add-local").

dub search <query> [<options...>]

Search all specified DUB registries for packages matching query.

add-override

dub add-override <package> <version-spec> <target-path/target-version> [<options...>]

Adds a new package override.

Available options:

 --system Register system-wide instead of user-wide

remove-override

dub remove-override <package> <version-spec> [<options...>]

Removes an existing package override.

Available options:

 --system Register system-wide instead of user-wide

list-overrides

dub list-overrides  [<options...>]

Prints a list of all overridden packages added via "dub add-override".

clean-caches

dub clean-caches  [<options...>]

This command removes any cached metadata like the list of available packages and their latest version.

convert

dub convert  [<options...>]

This command will convert between JSON and SDLang formatted package recipe files.

Warning: Beware that any formatting and comments within the package recipe will get lost in the conversion process.

Available options:

-f--format=<value> Specifies the target package recipe format. Possible values:
    json, sdl
-s--stdout Outputs the converted package recipe to stdout instead of writing to disk.