Skip to content


The packaging config.

Object Properties:

  • appimage
  • authors
  • beforeEachPackageCommand
  • beforePackagingCommand
  • binaries
  • category
  • copyright
  • deb
  • description
  • dmg
  • enabled
  • externalBinaries
  • fileAssociations
  • formats
  • homepage
  • icons
  • identifier
  • licenseFile
  • logLevel
  • longDescription
  • macos
  • name
  • nsis
  • outDir
  • pacman
  • productName
  • publisher
  • resources
  • targetTriple
  • version
  • windows
  • wix


AppImageConfig | null

AppImage configuration.


string[] | null

The package’s authors.


HookCommand | null

The command to run before packaging each format for an application.

This will run multiple times depending on the formats specifed.


HookCommand | null

The command to run before starting to package an application.

This runs only once.



The binaries to package.

Default: []


AppCategory | null

The app’s category.

string | null

The app’s copyright.


DebianConfig | null

Debian-specific configuration.


string | null

The package’s description.


DmgConfig | null

Dmg configuration.



Whether this config is enabled or not. Defaults to true.

Default: true


string[] | null

Paths to external binaries to add to the package.

The path specified should not include -<target-triple><.exe> suffix, it will be auto-added when by the packager when reading these paths, so the actual binary name should have the target platform’s target triple appended, as well as .exe for Windows.

For example, if you’re packaging an external binary called sqlite3, the packager expects a binary named sqlite3-x86_64-unknown-linux-gnu on linux, and sqlite3-x86_64-pc-windows-gnu.exe on windows.

If you are building a universal binary for MacOS, the packager expects your external binary to also be universal, and named after the target triple, e.g. sqlite3-universal-apple-darwin. See <>


FileAssociation[] | null

The file associations


PackageFormat[] | null

The packaging formats to create, if not present, [PackageFormat::platform_default] is used.


string | null

The package’s homepage.


string[] | null

The app’s icon list. Supports glob patterns.


string | null pattern of ^[a-zA-Z0-9-\.]*$

The application identifier in reverse domain name notation (e.g. com.packager.example). This string must be unique across applications since it is used in some system configurations. This string must contain only alphanumeric characters (A–Z, a–z, and 0–9), hyphens (-), and periods (.).


string | null

A path to the license file.


LogLevel | null

The logging level.


string | null

The app’s long description.


MacOsConfig | null

MacOS-specific configuration.


string | null

The app name, this is just an identifier that could be used to filter which app to package using --packages cli arg when there is multiple apps in the workspace or in the same config.

This field resembles, the name field in Cargo.toml or package.json

If unset, the CLI will try to auto-detect it from Cargo.toml or package.json otherwise, it will keep it unset.


NsisConfig | null

Nsis configuration.



The directory where the [Config::binaries] exist and where the generated packages will be placed.


PacmanConfig | null

Pacman configuration.



The package’s product name, for example “My Awesome App”.


string | null

The app’s publisher. Defaults to the second element in Config::identifier string. Currently maps to the Manufacturer property of the Windows Installer.


Resource[] | null

The app’s resources to package. This a list of either a glob pattern, path to a file, path to a directory or an object of src and target paths. In the case of using an object, the src could be either a glob pattern, path to a file, path to a directory, and the target is a path inside the final resources folder in the installed package.


  • [PackageFormat::Nsis] / [PackageFormat::Wix]: The resources are placed next to the executable in the root of the packager. - [PackageFormat::Deb]: The resources are placed in usr/lib of the package.


string | null

The target triple we are packaging for. This mainly affects [Config::external_binaries].

Defaults to the current OS target triple.



The package’s version.


WindowsConfig | null

Windows-specific configuration.


WixConfig | null

WiX configuration.



"Business" | "DeveloperTool" | "Education" | "Entertainment" | "Finance" | "Game" | "ActionGame" | "AdventureGame" | "ArcadeGame" | "BoardGame" | "CardGame" | "CasinoGame" | "DiceGame" | "EducationalGame" | "FamilyGame" | "KidsGame" | "MusicGame" | "PuzzleGame" | "RacingGame" | "RolePlayingGame" | "SimulationGame" | "SportsGame" | "StrategyGame" | "TriviaGame" | "WordGame" | "GraphicsAndDesign" | "HealthcareAndFitness" | "Lifestyle" | "Medical" | "Music" | "News" | "Photography" | "Productivity" | "Reference" | "SocialNetworking" | "Sports" | "Travel" | "Utility" | "Video" | "Weather"

The possible app categories. Corresponds to LSApplicationCategoryType on macOS and the GNOME desktop categories on Debian.


The Linux AppImage configuration.

Object Properties:

  • bins
  • files
  • libs
  • linuxdeployPlugins

string[] | null

List of binary paths to include in the final AppImage. For example, if you want xdg-open, you’d specify /usr/bin/xdg-open


| null

List of custom files to add to the appimage package. Maps a dir/file to a dir/file inside the appimage package.

Allows additional properties: string


string[] | null

List of libs that exist in /usr/lib* to be include in the final AppImage. The libs will be searched for, using the command find -L /usr/lib* -name &lt;libname&gt;


| null

A map of linuxdeploy plugin name and its URL to be downloaded and executed while packaing the appimage. For example, if you want to use the gtk plugin, you’d specify gtk as the key and its url as the value.

Allows additional properties: string


A binary to package within the final package.

Object Properties:

  • main
  • path (required)


Whether this is the main binary or not



Path to the binary (without .exe on Windows). If it’s relative, it will be resolved from [Config::out_dir].


One of the following:

  • "editor" CFBundleTypeRole.Editor. Files can be read and edited.
  • "viewer" CFBundleTypeRole.Viewer. Files can be read.
  • "shell" CFBundleTypeRole.Shell
  • "qLGenerator" CFBundleTypeRole.QLGenerator
  • "none" CFBundleTypeRole.None

macOS-only*. Corresponds to CFBundleTypeRole


The Linux debian configuration.

Object Properties:

  • depends
  • desktopTemplate
  • files
  • priority
  • section

string[] | null

The list of debian dependencies.


string | null

Path to a custom desktop file Handlebars template.

Available variables: categories, comment (optional), exec, icon and name.

Default file contents: text [Desktop Entry] Categories={{categories}} {{#if comment}} Comment={{comment}} {{/if}} Exec={{exec}} Icon={{icon}} Name={{name}} Terminal=false Type=Application {{#if mime_type}} MimeType={{mime_type}} {{/if}}


| null

List of custom files to add to the deb package. Maps a dir/file to a dir/file inside the debian package.

Allows additional properties: string


string | null

Change the priority of the Debian Package. By default, it is set to optional. Recognized Priorities as of now are : required, important, standard, optional, extra


string | null

Define the section in Debian Control file. See : <>


The Apple Disk Image (.dmg) configuration.

Object Properties:

  • appFolderPosition
  • appPosition
  • background
  • windowPosition
  • windowSize

Position | null

Position of application folder on window.


Position | null

Position of application file on window.


string | null

Image to use as the background in dmg file. Accepted formats: png/jpg/gif.


Position | null

Position of volume window on screen.


Size | null

Size of volume window.


A file association configuration.

Object Properties:

  • description
  • extensions (required)
  • mimeType
  • name
  • role

string | null

The association description. Windows-only. It is displayed on the Type column on Windows Explorer.



File extensions to associate with this app. e.g. ‘png’


string | null

The mime-type e.g. ‘image/png’ or ‘text/plain’. Linux-only.


string | null

The name. Maps to CFBundleTypeName on macOS. Defaults to the first item in ext



The app’s role with respect to the type. Maps to CFBundleTypeRole on macOS. Defaults to [BundleTypeRole::Editor]

Default: "editor"


Any of the following:

  • string Run the given script with the default options.
  • Run the given script with custom options. Object Properties: - dir - script (required) ##### dir string | null The working directory. ##### script string The script to execute.

Describes a shell command to be executed when a CLI hook is triggered.


One of the following:

  • "error" The “error” level. Designates very serious errors.
  • "warn" The “warn” level. Designates hazardous situations.
  • "info" The “info” level. Designates useful information.
  • "debug" The “debug” level. Designates lower priority information.
  • "trace" The “trace” level. Designates very low priority, often extremely verbose, information.

An enum representing the available verbosity levels of the logger.


The macOS configuration.

Object Properties:

  • entitlements
  • exceptionDomain
  • frameworks
  • infoPlistPath
  • minimumSystemVersion
  • providerShortName
  • signingIdentity

string | null

Path to the entitlements.plist file.


string | null

The exception domain to use on the macOS .app package.

This allows communication to the outside world e.g. a web server you’re shipping.


string[] | null

MacOS frameworks that need to be packaged with the app.

Each string can either be the name of a framework (without the .framework extension, e.g. "SDL2"), in which case we will search for that framework in the standard install locations (~/Library/Frameworks/, /Library/Frameworks/, and /Network/Library/Frameworks/), or a path to a specific framework bundle (e.g. ./data/frameworks/SDL2.framework). Note that this setting just makes cargo-packager copy the specified frameworks into the OS X app bundle (under; you are still responsible for:

  • arranging for the compiled binary to link against those frameworks (e.g. by emitting lines like cargo:rustc-link-lib=framework=SDL2 from your script)

  • embedding the correct rpath in your binary (e.g. by running install_name_tool -add_rpath "@executable_path/../Frameworks" path/to/binary after compiling)


string | null

Path to the Info.plist file for the package.


string | null

A version string indicating the minimum MacOS version that the packaged app supports (e.g. "10.11"). If you are using this config field, you may also want have your script emit cargo:rustc-env=MACOSX_DEPLOYMENT_TARGET=10.11.


string | null

Provider short name for notarization.


string | null

Code signing identity.


One of the following:

  • "zlib" ZLIB uses the deflate algorithm, it is a quick and simple method. With the default compression level it uses about 300 KB of memory.
  • "bzip2" BZIP2 usually gives better compression ratios than ZLIB, but it is a bit slower and uses more memory. With the default compression level it uses about 4 MB of memory.
  • "lzma" LZMA (default) is a new compression method that gives very good compression ratios. The decompression speed is high (10-20 MB/s on a 2 GHz CPU), the compression speed is lower. The memory size that will be used for decompression is the dictionary size plus a few KBs, the default is 8 MB.
  • "off" Disable compression.

Compression algorithms used in the NSIS installer.

See <>


The NSIS format configuration.

Object Properties:

  • appdataPaths
  • compression
  • customLanguageFiles
  • displayLanguageSelector
  • headerImage
  • installerIcon
  • installMode
  • languages
  • preinstallSection
  • sidebarImage
  • template

string[] | null

List of paths where your app stores data. This options tells the uninstaller to provide the user with an option (disabled by default) whether they want to rmeove your app data or keep it.

The path should use a constant from <> in addition to $IDENTIFIER, $PUBLISHER and $PRODUCTNAME, for example, if you store your app data in C:\\Users\\&lt;user&gt;\\AppData\\Local\\&lt;your-company-name&gt;\\&lt;your-product-name&gt; you’d need to specify toml [package.metadata.packager.nsis] appdata-paths = ["$LOCALAPPDATA/$PUBLISHER/$PRODUCTNAME"]


NsisCompression | null

Set the compression algorithm used to compress files in the installer.

See <>


| null

An key-value pair where the key is the language and the value is the path to a custom .nsi file that holds the translated text for cargo-packager’s custom messages.

See <> for an example .nsi file.

Note: the key must be a valid NSIS language and it must be added to [NsisConfig]languages array,

Allows additional properties: string



Whether to display a language selector dialog before the installer and uninstaller windows are rendered or not. By default the OS language is selected, with a fallback to the first language in the languages array.


string | null

The path to a bitmap file to display on the header of installers pages.

The recommended dimensions are 150px x 57px.


string | null

The path to an icon file used as the installer icon.



Whether the installation will be for all users or just the current user.

Default: "currentUser"


string[] | null

A list of installer languages. By default the OS language is used. If the OS language is not in the list of languages, the first language will be used. To allow the user to select the language, set display_language_selector to true.

See <> for the complete list of languages.


string | null

Logic of an NSIS section that will be ran before the install section.

See the available libraries, dlls and global variables here <>

Example ```toml [package.metadata.packager.nsis] preinstall-section = """ ; Setup custom messages LangString webview2AbortError ${LANG_ENGLISH} “Failed to install WebView2! The app can’t run without it. Try restarting the installer.” LangString webview2DownloadError ${LANG_ARABIC} “خطأ: فشل تنزيل WebView2 - $0”

Section PreInstall ; <section logic here> SectionEnd

Section AnotherPreInstall ; <section logic here> SectionEnd """ ```


string | null

The path to a bitmap file for the Welcome page and the Finish page.

The recommended dimensions are 164px x 314px.


string | null

A custom .nsi template to use.

See the default template here <>


One of the following:

  • "currentUser" Default mode for the installer. Install the app by default in a directory that doesn’t require Administrator access. Installer metadata will be saved under the HKCU registry path.
  • "perMachine" Install the app by default in the Program Files folder directory requires Administrator access for the installation. Installer metadata will be saved under the HKLM registry path.
  • "both" Combines both modes and allows the user to choose at install time whether to install for the current user or per machine. Note that this mode will require Administrator access even if the user wants to install it for the current user only. Installer metadata will be saved under the HKLM or HKCU registry path based on the user’s choice.

Install Modes for the NSIS installer.


One of the following:

  • "all" All available package formats for the current platform. See [PackageFormat::platform_all]
  • "default" The default list of package formats for the current platform. See [PackageFormat::platform_default]
  • "app" The macOS application bundle (.app).
  • "dmg" The macOS DMG package (.dmg).
  • "wix" The Microsoft Software Installer (.msi) through WiX Toolset.
  • "nsis" The NSIS installer (.exe).
  • "deb" The Linux Debian package (.deb).
  • "appimage" The Linux AppImage package (.AppImage).
  • "pacman" The Linux Pacman package (.tar.gz and PKGBUILD)

Types of supported packages by cargo-packager.


The Linux pacman configuration.

Object Properties:

  • conflicts
  • depends
  • files
  • provides
  • replaces
  • source

string[] | null

Packages that conflict or cause problems with the app. All these packages and packages providing this item will need to be removed

See : <>


string[] | null

List of softwares that must be installed for the app to build and run.

See : <>


| null

List of custom files to add to the pacman package. Maps a dir/file to a dir/file inside the pacman package.

Allows additional properties: string


string[] | null

Additional packages that are provided by this app.

See : <>


string[] | null

Only use if this app replaces some obsolete packages. For example, if you rename any package.

See : <>


string[] | null

Source of the package to be stored at PKGBUILD. PKGBUILD is a bash script, so version can be referred as ${pkgver}


Position coordinates struct.

Object Properties:

  • x (required)
  • y (required)

integer formatted as uint32

X coordinate.


integer formatted as uint32

Y coordinate.


Any of the following:

  • string Supports glob patterns
  • An object descriping the src file or directory and its target location in the final package. Object Properties: - src (required) - target (required) ##### src string The src file or directory, supports glob patterns. ##### target string A relative path from the root of the final package. If src is a glob, this will always be treated as a directory where all globbed files will be placed under.

A path to a resource (with optional glob pattern) or an object of src and target paths.


Size struct.

Object Properties:

  • height (required)
  • width (required)

integer formatted as uint32



integer formatted as uint32



The Windows configuration.

Object Properties:

  • allowDowngrades
  • certificateThumbprint
  • digestAlgorithm
  • signCommand
  • timestampUrl
  • tsp


Whether to validate a second app installation, blocking the user from installing an older version if set to false.

For instance, if 1.2.1 is installed, the user won’t be able to install app version 1.2.0 or 1.1.5.

The default value of this flag is true.

Default: true


string | null

The SHA1 hash of the signing certificate.


string | null

The file digest algorithm to use for creating file signatures. Required for code signing. SHA-256 is recommended.


string | null

Specify a custom command to sign the binaries. This command needs to have a %1 in it which is just a placeholder for the binary path, which we will detect and replace before calling the command.

By Default we use signtool.exe which can be found only on Windows so if you are on another platform and want to cross-compile and sign you will need to use another tool like osslsigncode.


string | null

Server to use during timestamping.



Whether to use Time-Stamp Protocol (TSP, a.k.a. RFC 3161) for the timestamp server. Your code signing provider may use a TSP timestamp server, like e.g. does. If so, enable TSP by setting to true.


The wix format configuration

Object Properties:

  • bannerPath
  • componentGroupRefs
  • componentRefs
  • customActionRefs
  • dialogImagePath
  • featureGroupRefs
  • featureRefs
  • fipsCompliant
  • fragmentPaths
  • fragments
  • languages
  • mergeModules
  • mergeRefs
  • template

string | null

Path to a bitmap file to use as the installation user interface banner. This bitmap will appear at the top of all but the first page of the installer.

The required dimensions are 493px × 58px.


string[] | null

The ComponentGroup element ids you want to reference from the fragments.


string[] | null

The Component element ids you want to reference from the fragments.


string[] | null

The CustomAction element ids you want to reference from the fragments.


string | null

Path to a bitmap file to use on the installation user interface dialogs. It is used on the welcome and completion dialogs. The required dimensions are 493px × 312px.


string[] | null

The FeatureGroup element ids you want to reference from the fragments.


string[] | null

The Feature element ids you want to reference from the fragments.



Enables FIPS compliant algorithms.


string[] | null

A list of paths to .wxs files with WiX fragments to use.


string[] | null

List of WiX fragments as strings. This is similar to config.wix.fragments_paths but is a string so you can define it inline in your config.

text &lt;?xml version="1.0" encoding="utf-8"?&gt; &lt;Wix xmlns=""&gt; &lt;Fragment&gt; &lt;CustomAction Id="OpenNotepad" Directory="INSTALLDIR" Execute="immediate" ExeCommand="cmd.exe /c notepad.exe" Return="check" /&gt; &lt;InstallExecuteSequence&gt; &lt;Custom Action="OpenNotepad" After="InstallInitialize" /&gt; &lt;/InstallExecuteSequence&gt; &lt;/Fragment&gt; &lt;/Wix&gt;


WixLanguage[] | null

The app languages to build. See <>.


string[] | null

List of merge modules to include in your installer. For example, if you want to include C++ Redis merge modules


string[] | null

The Merge element ids you want to reference from the fragments.


string | null

By default, the packager uses an internal template. This option allows you to define your own wix file.


Any of the following:

A wix language.