Vcpkg: Overview

中文总览 Español 한국어 Français Tiếng Việt

Vcpkg helps you manage C and C++ libraries on Windows, Linux and MacOS. This tool and ecosystem are constantly evolving, and we always appreciate contributions!

If you’ve never used vcpkg before, or if you’re trying to figure out how to use vcpkg, check out our Getting Started section for how to start using vcpkg.

For short description of available commands, once you’ve installed vcpkg, you can run vcpkg help, or vcpkg help [command] for command-specific help.

GitHub: ports at https://github.com/microsoft/vcpkg, program at https://github.com/microsoft/vcpkg-tool
Slack: https://cppalliance.org/slack/, the #vcpkg channel
Discord: #include <C++>, the #🌏vcpkg channel
Docs: Documentation

Quick Start: Windows

Prerequisites:

Windows 7 or newer
Git
Visual Studio 2015 Update 3 or greater with the English language pack

First, download and bootstrap vcpkg itself; it can be installed anywhere, but generally we recommend using vcpkg as a submodule so the consuming repo can stay self-contained. Alternatively, vcpkg can be installed globally; we recommend somewhere like C:\src\vcpkg or C:\dev\vcpkg, since otherwise you may run into path issues for some port build systems.

> git clone https://github.com/microsoft/vcpkg
> .\vcpkg\bootstrap-vcpkg.bat

To install the libraries for your project, run:

> .\vcpkg\vcpkg install [packages to install]

Note: This will install x86 libraries by default. To install x64, run:

> .\vcpkg\vcpkg install [package name]:x64-windows

> .\vcpkg\vcpkg install [packages to install] --triplet=x64-windows

You can also search for the libraries you need with the search subcommand:

> .\vcpkg\vcpkg search [search term]

In order to use vcpkg with Visual Studio, run the following command (may require administrator elevation):

> .\vcpkg\vcpkg integrate install

After this, you can now create a New non-CMake Project (or open an existing one). All installed libraries are immediately ready to be #include’d and used in your project without additional configuration.

If you’re using CMake with Visual Studio, continue here.

In order to use vcpkg with CMake outside of an IDE, you can use the toolchain file:

> cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
> cmake --build [build directory]

With CMake, you will still need to find_package and the like to use the libraries. Check out the CMake section for more information, including on using CMake with an IDE.

Quick Start: Unix

Prerequisites for Linux:

Git
g++ >= 6

Prerequisites for macOS:

Apple Developer Tools

First, download and bootstrap vcpkg itself; it can be installed anywhere, but generally we recommend using vcpkg as a submodule.

$ git clone https://github.com/microsoft/vcpkg
$ ./vcpkg/bootstrap-vcpkg.sh

To install the libraries for your project, run:

$ ./vcpkg/vcpkg install [packages to install]

You can also search for the libraries you need with the search subcommand:

$ ./vcpkg/vcpkg search [search term]

In order to use vcpkg with CMake, you can use the toolchain file:

$ cmake -B [build directory] -S . "-DCMAKE_TOOLCHAIN_FILE=[path to vcpkg]/scripts/buildsystems/vcpkg.cmake"
$ cmake --build [build directory]

With CMake, you will still need to find_package and the like to use the libraries. Check out the CMake section for more information on how best to use vcpkg with CMake, and CMake Tools for VSCode.

Installing macOS Developer Tools

On macOS, the only thing you should need to do is run the following in your terminal:

$ xcode-select --install

Then follow along with the prompts in the windows that comes up.

You’ll then be able to bootstrap vcpkg along with the quick start guide

Using vcpkg with CMake

Visual Studio Code with CMake Tools

Adding the following to your workspace settings.json will make CMake Tools automatically use vcpkg for libraries:

{
  "cmake.configureSettings": {
    "CMAKE_TOOLCHAIN_FILE": "[vcpkg root]/scripts/buildsystems/vcpkg.cmake"
  }
}

Vcpkg with Visual Studio CMake Projects

Open the CMake Settings Editor, and under CMake toolchain file, add the path to the vcpkg toolchain file:

[vcpkg root]/scripts/buildsystems/vcpkg.cmake

Vcpkg with CLion

Vcpkg is integrated in the CLion IDE. For details, see the official documentation.

Vcpkg as a Submodule with CMake

When using vcpkg as a submodule of your project, you can add the following to your CMakeLists.txt before the first project() call, instead of passing CMAKE_TOOLCHAIN_FILE to the cmake invocation.

set(CMAKE_TOOLCHAIN_FILE "${CMAKE_CURRENT_SOURCE_DIR}/vcpkg/scripts/buildsystems/vcpkg.cmake"
  CACHE STRING "Vcpkg toolchain file")

This will still allow people to not use vcpkg, by passing the CMAKE_TOOLCHAIN_FILE directly, but it will make the configure-build step slightly easier.

Examples

See the documentation for specific walkthroughs, including installing and using a package, adding a new package from a zipfile, and adding a new package from a GitHub repo.

Our docs are now also available online at our website https://vcpkg.io/. We really appreciate any and all feedback! You can submit an issue in https://github.com/vcpkg/vcpkg.github.io/issues.

See a 4 minute video demo.

Security

Most ports in vcpkg build the libraries in question using the original build system preferred by the original developers of those libraries, and download source code and build tools from their official distribution locations. For use behind a firewall, the specific access needed will depend on which ports are being installed. If you must install it in an “air gapped” environment, consider installing once in a non-“air gapped” environment, populating an asset cache shared with the otherwise “air gapped” environment.

Vcpkg