vcpkg.json Reference

Article
07/22/2024

For an overview of using manifests with vcpkg, see Manifest mode.

Manifests are strict JSON documents. They cannot contain C++-style comments (//) nor trailing commas. However you can use field names that start with $ to write your comments in any object that has a well-defined set of keys. These comment fields are not allowed in any objects which permit user-defined keys (such as "features").

The latest JSON Schema is available at https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json. IDEs with JSON Schema support such as Visual Studio and Visual Studio Code can use this file to provide autocomplete and syntax checking. For most IDEs, you should set "$schema" in your vcpkg.json to this URL.

Example

{
  "$schema": "https://raw.githubusercontent.com/microsoft/vcpkg-tool/main/docs/vcpkg.schema.json",
  "dependencies": [
    "boost-system",
    {
      "name": "cpprestsdk",
      "default-features": false
    },
    "libxml2",
    "yajl"
  ]
}

This example demonstrates a manifest for an application using boost-system, cpprestsdk, libxml2, and yajl. The example also includes a $schema reference to enable better IDE validation and autocompletion.

Top-level Fields

Name	Required	Type	Description
builtin-baseline	No	string	Version pins to use when building as top-level
default-features	No	Feature Object[]	Require the features listed as on-by-default
dependencies	No	Dependency[]	List of dependencies required to build and use this project
description	Libraries	string or string[]	The project description
documentation	No	string	URI to the upstream project's documentation
features	No	{string: Feature}	Optional features available for users of the project
homepage	No	string	URI to the upstream project's homepage
license	No	string or null	SPDX license expression
maintainers	No	string or string[]	Maintainers of the package files
name	Libraries	string	The project name
overrides	No	Override[]	Version pins to use when building as top-level
port-version	No	integer	Port files revision
supports	No	Platform Expression	Supported platform and build configurations
version version-semver version-date version-string	Libraries	string	Upstream version information

`"builtin-baseline"`

A shortcut for specifying the "baseline" for version resolution in the default registry. A string. Optional, only used by top-level projects.

This field indicates the commit of https://github.com/microsoft/vcpkg which provides global minimum version information for your manifest. It is required for top-level manifest files using versioning without a specified "default-registry". It has the same semantic as defining your default registry to be:

{
  "default-registry": {
    "kind": "builtin",
    "baseline": "<value>"
  }
}

See versioning and Using registries for more semantic details.

`"default-features"`

The set of features needed for reasonable behavior without additional customization.

The default features are automatically selected if either:

A port-to-port dependency for the port has "default-features": true -- the default value.
The top-level manifest does not have a dependency for the port with "default-features": false.

Default features handle the specific case of providing a "default" configuration for transitive dependencies that the top-level project may not know about. Ports used by others should almost always use "default-features": false for their dependencies.

You can define platform-specific default features by using a Feature Object:

{
  "name": "my-port",
  "default-features": [
    "png",
    {
      "name": "winssl",
      "platform": "windows"
    }
  ]
}

See "features" for more information about features.

`"description"`

The description of the port. A string or array of strings. Required for libraries, optional for top-level projects.

This is used to help users discover the library as part of a search or find command and learn what the library does.

`"dependencies"`

The list of dependencies required by the project. An array of Dependency objects. Optional.

This field lists all the dependencies needed to build and use your library or application.

Example port dependencies

"dependencies": [
  {
    "name": "arrow",
    "default-features": false,
    "features": [
      "json",
      {
        "name": "mimalloc",
        "platform": "windows"
      }
    ]
  },
  "boost-asio",
  "openssl",
  {
    "name": "picosha2",
    "platform": "!windows"
  }
]

`"documentation"`

The URI to the upstream project's documentation. A string. Optional.

`"features"`

The features available for users of the project. A map of names to Feature objects. Optional.

Features are boolean flags that add additional behaviors and dependencies to a build. See the Manifest Concept Documentation for more information about features.

`"homepage"`

The URI to the project's homepage. A string. Optional.

`"license"`

The SPDX short license expression of the project. A string or null. Optional.

The "license" should either be an SPDX 3.19 license expression or should be null to indicate that users must read the deployed /share/<port>/copyright file. DocumentRefs are not supported.

Note

The licensing information provided for each package in the vcpkg registry represents Microsoft's best understanding of the licensing requirements. However, this information may not be definitive. Users are advised to verify the exact licensing requirements for each package they intend to use, as it is ultimately their responsibility to ensure compliance with the applicable licenses.

Example license strings

MIT
LGPL-2.1-only AND BSD-2-Clause
GPL-2.0-or-later WITH Bison-exception-2.2

EBNF

vcpkg uses the following EBNF to parse the license field:

idchar = ? regex /[-.a-zA-Z0-9]/ ?
idstring = ( idchar ), { idchar } ;

(* note that unrecognized license and license exception IDs will be warned against *)
license-id = idstring ;
license-exception-id = idstring ;
(* note that DocumentRefs are unsupported by this implementation *)
license-ref = "LicenseRef-", idstring ;

with = [ whitespace ], "WITH", [ whitespace ] ;
and = [ whitespace ], "AND", [ whitespace ] ;
or = [ whitespace ], "OR", [ whitespace ] ;

simple-expression = [ whitespace ], (
  | license-id
  | license-id, "+"
  | license-ref
  ), [ whitespace ] ;

(* the following are split up from compound-expression to make precedence obvious *)
parenthesized-expression =
  | simple-expression
  | [ whitespace ], "(", or-expression, ")", [ whitespace ] ;

with-expression =
  | parenthesized-expression
  | simple-expression, with, license-exception-id, [ whitespace ] ;

(* note: "a AND b OR c" gets parsed as "(a AND b) OR c" *)
and-expression = with-expression, { and, with-expression } ;
or-expression = and-expression, { or, and-exression } ;

license-expression = or-expression ;

`"maintainers"`

The list of package maintainers. A string or array of strings. Optional.

We recommend using the form "Givenname Surname <email>".

`"name"`

The name of the project. A string. Required for libraries, optional for top-level projects.

The name must be lowercase ASCII letters, digits, or hyphens (-). It must not start nor end with a hyphen. Libraries are encouraged to include their organization or framework name as a prefix, such as msft- or boost- to help users find and describe associated libraries.

For example, a library with an official name of Boost.Asio might be given the name boost-asio.

`"overrides"`

Exact version pins to use for specific dependencies. An array of Override objects. Optional.

"overrides" from transitive manifests (i.e. from dependencies) are ignored. Only overrides defined by the top-level project are used.

Name	Required	Type	Description
name	Yes	string	The port name
version	Yes	string	Upstream version information to pin.
version-semver version-date version-string	Yes	string	Deprecated alternatives to `version` naming particular schemes.
port-version	No	integer	Port files revision to pin. Deprecated in favor of being placed into the version itself.

"port-version" should be specified as a #N suffix in "version". For example, "version": "1.2.3#7" names version 1.2.3, port-version 7.

See also versioning for more semantic details.

Example of version overrides

  "overrides": [
    {
      "name": "arrow", "version": "1.2.3#7"
    },
    {
      "name": "openssl", "version": "1.1.1h#3"
    }
  ]

`"port-version"`

A version suffix distinguishing revisions to the packaging files. An integer. Defaults to 0.

The "port-version" should be incremented whenever a new version of the port is published that does not change the upstream source version. When the upstream source version is changed, the version field should change and the "port-version" should be reset to 0 (or removed).

See versioning for more details.

`"supports"`

Supported platform and build configurations. A Platform Expression. Optional.

This field documents that a project is not expected to build or run successfully on certain platform configurations.

For example, if your library doesn't support building for Linux, you would use "supports": "!linux".

`"vcpkg-configuration"`

Allows to embed vcpkg configuration properties inside the vcpkg.json file. Everything inside the vcpkg-configuration property is treated as if it were defined in a vcpkg-configuration.json file. For more details, see the vcpkg-configuration.json documentation.

Having a vcpkg-configuration defined in vcpkg.json while also having a vcpkg-configuration.json file is not allowed and will result in the vcpkg command terminating with an error message.

Example embedded `vcpkg-configuration`

{
  "name": "test",
  "version": "1.0.0",
  "dependencies": [ "beison", "zlib" ],
  "vcpkg-configuration": {
    "registries": [
      {
        "kind": "git",
        "baseline": "768f6a3ad9f9b6c4c2ff390137690cf26e3c3453",
        "repository": "https://github.com/microsoft/vcpkg-docs",
        "reference": "vcpkg-registry",
        "packages": [ "beicode", "beison" ]
      }
    ],
    "overlay-ports": [ "./my-ports/fmt", 
                       "./team-ports"
    ]
  }

`"version"`, `"version-semver"`, `"version-date"`, `"version-string"`

The version of the upstream project. A string. Required for libraries, optional for top-level projects.

A manifest must contain at most one version field. Each version field corresponds to a different versioning scheme:

"version" - Relaxed Semantic Version 2.0.0, allowing more or less than 3 primary numbers. Example: 1.2.3.4.10-alpha1
"version-semver" - Strict Semantic Version 2.0.0. Example: 2.0.1-rc5
"version-date" - A date formatted as YYYY-MM-DD with an optional trailing dot-separate numeric sequence. Used for packages which do not have numeric releases (for example, Live-at-HEAD). Example: 2022-12-09.314562
"version-string" - An arbitrary string. Used for packages that don't have orderable versions. This should be rarely used, however all ports created before the other version fields were introduced use this scheme.

See versioning for more details.

Dependency Fields

Each dependency is a string or an object with the following fields:

Name	Required	Type	Description
default-features	No	bool	Require the features listed as on-by-default
features	No	Feature Object[]	The list of additional features to require
host	No	bool	Require the dependency for the host machine instead of the target
name	Yes	string	The name of the dependency
platform	No	Platform Expression	Qualifier for which platforms to use the dependency
version>=	No	string	Minimum required version. Port-version is identified with a `#N` suffix, for example, `1.2.3#7` names port-version 7.

Strings are interpreted as an object with name defined to the string value.

Dependency: `"default-features"`

A boolean indicating that the project depends on the 'on-by-default' features of the dependency. Defaults to true.

In most cases, this should be defined to false and any needed features should be explicitly depended upon.

Dependency: `"features"`

The list of additional features to require. An array of Feature objects. Optional.

A Feature Object is an object with the following fields:

name - The name of the feature. A string. Required.
platform - A Platform Expression that limits the platforms where the feature is required. Optional.

A simple string is also a valid Feature Object equivalent to { "name": "<feature-name>" }.

For example,

{
  "name": "ffmpeg",
  "default-features": false,
  "features": [
    "mp3lame",
    {
      "name": "avisynthplus",
      "platform": "windows"
    }  
  ]
}

Uses the ffmpeg library with mp3 encoding support. On Windows only, avisynthplus support is also enabled.

Dependency: `"host"`

A boolean indicating that the dependency must be built for the host triplet instead of the current port's triplet. Defaults to false.

Any dependency that provides tools or scripts which should be "executed" during a build (such as buildsystems, code generators, or helpers) should be marked as "host": true. This enables correct cross-compilation in cases that the target is not executable -- such as when compiling for arm64-android.

See Host dependencies for more information.

Dependency: `"name"`

The name of the dependency. A string. Required.

This follows the same restrictions as the "name" property for a project.

Dependency: `"platform"`

An expression that limits the platforms where the dependency is required. A Platform Expression. Optional.

If the expression does not match the current configuration, the dependency will not be used. For example, if a dependency has "platform": "!windows", it only be required when targeting non-Windows systems.

Dependency: `"version>="`

A minimum version constraint on the dependency.

This field specifies the minimum version of the dependency, optionally using a #N suffix to also specify a minimum port-version if desired.

For more information on versioning semantics, see Versioning.

Feature Fields

Each feature is an object with the following fields:

Name	Required	Type	Description
description	Yes	string	The description of the feature
dependencies	No	Dependency[]	A list of dependencies
supports	No	Platform Expression	Qualifier for which platforms and configurations the feature supports
license	No	string or null	SPDX license expression

Check out the Manifest mode documentation for a conceptual overview of features.

Example port with features

{
  "features": {
    "cbor": {
      "description": "The CBOR backend",
      "dependencies": [
        {
          "$explanation": [
            "This is how you tell vcpkg that the cbor feature depends on the json feature of this package"
          ],
          "name": "libdb",
          "default-features": false,
          "features": [ "json" ]
        }
      ]
    },
    "csv": {
      "description": "The CSV backend",
      "dependencies": [
        "fast-cpp-csv-parser"
      ]
    },
    "json": {
      "description": "The JSON backend",
      "dependencies": [
        "jsoncons"
      ]
    }
  }
}

Feature: `"dependencies"`

The list of dependencies required by the feature. An array of Dependency objects. Optional.

This field lists any additional dependencies needed to build and use the feature.

Feature: `"description"`

The description of the feature. A string or array of strings. Required.

This is used to help users discover the feature as part of a search or find command and learn what the feature does.

Feature: `"supports"`

The supported platform and build configurations for the feature. A Platform Expression. Optional.

This field documents the platform configurations where the feature will build and run successfully.

Feature: `"license"`

The SPDX short license expression of the feature. A string or null. Optional. If not provided, the license is the same as specified in the top level license field.

Note

Platform Expression

A Platform Expression is a JSON string which describes when a dependency is required or when a library or feature is expected to build.

Expressions are built from primitive identifiers, logical operators, and grouping:

!<expr>, not <expr> - negation
<expr>|<expr>, <expr>,<expr> - logical OR (the keyword or is reserved but not valid in platform expressions)
<expr>&<expr>, <expr> and <expr> - logical AND
(<expr>) - grouping/precedence

The following identifiers are defined based on the triplet settings and build configuration:

Identifier	Triplet Condition
`x64`	`VCPKG_TARGET_ARCHITECTURE` == `"x64"`
`x86`	`VCPKG_TARGET_ARCHITECTURE` == `"x86"`
`arm`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"` or `VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`arm32`	`VCPKG_TARGET_ARCHITECTURE` == `"arm"`
`arm64`	`VCPKG_TARGET_ARCHITECTURE` == `"arm64"`
`arm64ec`	`VCPKG_TARGET_ARCHITECTURE` == `"arm64ec"`
`wasm32`	`VCPKG_TARGET_ARCHITECTURE` == `"wasm32"`
`mips64`	`VCPKG_TARGET_ARCHITECTURE` == `"mips64"`
`windows`	`VCPKG_CMAKE_SYSTEM_NAME` == `""` or `VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"` or `VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
`mingw`	`VCPKG_CMAKE_SYSTEM_NAME` == `"MinGW"`
`uwp`	`VCPKG_CMAKE_SYSTEM_NAME` == `"WindowsStore"`
`xbox`	`VCPKG_CMAKE_SYSTEM_NAME` == `""` and `XBOX_CONSOLE_TARGET` is defined.
`linux`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Linux"`
`osx`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Darwin"`
`ios`	`VCPKG_CMAKE_SYSTEM_NAME` == `"iOS"`
`freebsd`	`VCPKG_CMAKE_SYSTEM_NAME` == `"FreeBSD"`
`openbsd`	`VCPKG_CMAKE_SYSTEM_NAME` == `"OpenBSD"`
`android`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Android"`
`emscripten`	`VCPKG_CMAKE_SYSTEM_NAME` == `"Emscripten"`
`qnx`	`VCPKG_CMAKE_SYSTEM_NAME` == `"QNX"`
`vxworks`	`VCPKG_CMAKE_SYSTEM_NAME` == `"VxWorks"`
`static`	`VCPKG_LIBRARY_LINKAGE` == `"static"`
`staticcrt`	`VCPKG_CRT_LINKAGE` == `"static"`
`native`	`TARGET_TRIPLET` == `HOST_TRIPLET`

Example platform expression

Needs picosha2 for sha256 on non-Windows, but get it from the OS on Windows (BCrypt)

{
  "name": "picosha2",
  "platform": "!windows"
}

Require zlib on arm64 Windows and amd64 Linux

{
  "name": "zlib",
  "platform": "(windows & arm64) | (linux & x64)"
}

Share via

vcpkg.json Reference

Example

Top-level Fields

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

Example port dependencies

`"documentation"`

`"features"`

`"homepage"`

`"license"`

Example license strings

EBNF

`"maintainers"`

`"name"`

`"overrides"`

Example of version overrides

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Example embedded `vcpkg-configuration`

`"version"`, `"version-semver"`, `"version-date"`, `"version-string"`

Dependency Fields

Dependency: `"default-features"`

Dependency: `"features"`

Dependency: `"host"`

Dependency: `"name"`

Dependency: `"platform"`

Dependency: `"version>="`

Feature Fields

Example port with features

Feature: `"dependencies"`

Feature: `"description"`

Feature: `"supports"`

Feature: `"license"`

Platform Expression

Example platform expression

Additional resources

Share via

vcpkg.json Reference

Example

Top-level Fields

"builtin-baseline"

"default-features"

"description"

"dependencies"

Example port dependencies

"documentation"

"features"

"homepage"

"license"

Example license strings

EBNF

"maintainers"

"name"

"overrides"

Example of version overrides

"port-version"

"supports"

"vcpkg-configuration"

Example embedded vcpkg-configuration

"version", "version-semver", "version-date", "version-string"

Dependency Fields

Dependency: "default-features"

Dependency: "features"

Dependency: "host"

Dependency: "name"

Dependency: "platform"

Dependency: "version>="

Feature Fields

Example port with features

Feature: "dependencies"

Feature: "description"

Feature: "supports"

Feature: "license"

Platform Expression

Example platform expression

Additional resources

`"builtin-baseline"`

`"default-features"`

`"description"`

`"dependencies"`

`"documentation"`

`"features"`

`"homepage"`

`"license"`

`"maintainers"`

`"name"`

`"overrides"`

`"port-version"`

`"supports"`

`"vcpkg-configuration"`

Example embedded `vcpkg-configuration`

`"version"`, `"version-semver"`, `"version-date"`, `"version-string"`

Dependency: `"default-features"`

Dependency: `"features"`

Dependency: `"host"`

Dependency: `"name"`

Dependency: `"platform"`

Dependency: `"version>="`

Feature: `"dependencies"`

Feature: `"description"`

Feature: `"supports"`

Feature: `"license"`