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 registry URL first when resolving dependencies. Can be specified multiple times. Available registry types:
    DUB: URL to DUB registry (default)
    Maven: URL to Maven repository + group id containing dub packages as artifacts. E.g. mvn+http://localhost:8040/maven/libs-release/dubpackages
 --skip-registry=<value> Sets a mode for skipping the search on certain package registry types:
    none: Search all configured or default registries (default)
    standard: Don't search the main registry (e.g. https://code.dlang.org/)
    configured: Skip all default and user configured registries
    all: Only search registries specified with --registry
 --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
 --verror Only print 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...>] -- <application arguments>

Initializes an empty package of the specified type in the given directory. By default, the current working directory 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
custom - custom project provided by dub package
-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>[@<version-spec>]] [<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
-y--yes Automatic yes to prompts. Assume "yes" as answer to all interactive prompts.
-n--non-interactive Don't enter interactive mode.
-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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.
 --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>[@<version-spec>]] [<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
-y--yes Automatic yes to prompts. Assume "yes" as answer to all interactive prompts.
-n--non-interactive Don't enter interactive mode.
-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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.
 --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>[@<version-spec>]] [<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.
 --parallel Runs multiple compiler instances in parallel, if possible.
-f--force Forces a recompilation even if the target is up to date
 --coverage Enables code coverage statistics to be generated.
 --coverage-ctfe Enables code coverage (including CTFE) 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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.

lint

dub lint [<package>[@<version-spec>]] [<options...>] -- <application arguments>

Builds the package and executes D-Scanner linter tests.

Available options:

 --syntax-check Lexes and parses sourceFile, printing the line and column number of any syntax errors to stdout.
 --style-check Lexes and parses sourceFiles, printing the line and column number of any static analysis check failures stdout.
 --error-format=<value> Format errors produced by the style/syntax checkers.
 --report Generate a static analysis report in JSON format.
 --report-format=<value> Specifies the format of the generated report.
 --report-file=<value> Write report to file.
 --import-paths=<value> Import paths
 --config=<value> Use the given configuration file.
-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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.

generate

dub generate <generator> [<package>[@<version-spec>]] [<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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.
 --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>[@<version-spec>]] [<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, pre-run-commands, post-run-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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.
 --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
 --no-redirect Don't redirect stdout/stderr streams of the test command
 --strategy=<value> Set strategy (careful/lookback/pingpong/indepth/inbreadth)
-j  Set number of look-ahead processes
 --trace Save all attempted reductions to DIR.trace
-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, plain, release, release-debug, release-nobounds, unittest, profile, profile-gc, docs, ddox, cov, cov-ctfe, unittest-cov, unittest-cov-ctfe, syntax 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 resolve missing 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.
 --filter-versions [Experimental] Filter version identifiers and debug version identifiers to improve build cache efficiency.

Package management commands

fetch

dub fetch <package>[@<version-spec>] [<options...>]

Note: Use "dub add <dependency>" 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 in a place where several applications can share them. If you just have a dependency to add, use the `add` command. 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 --cache=local
$ dub run vibelog --cache=local

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

add

dub add <package>[@<version-spec>] [<packages...>] [<options...>]

Adds <packages> as dependencies.

Running "dub add <package>" is the same as adding <package> to the "dependencies" section in dub.json/dub.sdl.
If no version is specified for one of the packages, dub will query the registry for the latest version.

remove

dub remove <package>[@<version-spec>] [<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>.
 --dry-run Only print what would be upgraded, but don't actually upgrade anything.
 --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 [<package>[@<version-spec>]] [<options...>]

Prints a list of all or selected 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"). If package specified output filtered by package spec.

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.