Deployers

Deployers are a mechanism to facilitate copying files from one folder, usually the Conan cache, to user folders. While Conan provides three built-in ones (full_deploy, direct_deploy and runtime_deploy), users can easily manage their own with conan config install.

Deployers run before generators, and they can change the target folders. For example, if the --deployer=full_deploy deployer runs before CMakeDeps, the files generated by CMakeDeps will point to the local copy in the user folder done by the full_deploy deployer, and not to the Conan cache. Multiple deployers can be specified by supplying more than one --deployer= argument, and they will be ran in order of appearance.

Deployers can be multi-configuration. Running conan install . --deployer=full_deploy repeatedly for different profiles can achieve a fully self-contained project, including all the artifacts, binaries, and build files. This project will be completely independent of Conan and no longer require it at all to build. Use the --deployer-folder argument to change the base folder output path for the deployer as desired.

Built-in deployers

Warning

The built-in deployers are in preview. See the Conan stability section for more information.

full_deploy

Deploys each package folder of every dependency to your recipe’s output_folder in a subfolder tree based on:

  1. The build context

  2. The dependency name and version

  3. The build type

  4. The build arch

Then every dependency will end up in a folder such as:

[OUTPUT_FOLDER]/full_deploy/host/dep/0.1/Release/x86_64

See a full example of the usage of full_deploy deployer in Creating a Conan-agnostic deploy of dependencies for developer use.

Note

Editable packages and skipped binaries

  • Dependencies whose package_folder is None (for example, skipped binaries that are not necessary) are not deployed.

  • Dependencies in editable mode are not skipped. Their package_folder is the local project root folder, so the whole contents of that folder (sources, build outputs, etc.) will be copied to the deployed folder. This is generally harmless, but it is usually not what is wanted, and the general recommendation is to not deploy editable packages.

  • If a different behavior is needed, such as skipping editables or raising an error, use a custom deployer. See Customize the full_deploy deployer: handling editable packages for the full implementation of full_deploy and how to adapt it.

  • The built-in deployers are mostly a convenience and an example. For real production needs, the expectation is to provide custom deployers and install them with conan config install or conan config install-pkg.

direct_deploy

Same as full_deploy, but only processes your recipe’s direct dependencies. This deployer will output your dependencies in a tree folder such as:

[OUTPUT_FOLDER]/direct_deploy/dep

runtime_deploy

New since Conan 2.5.0

Copies all shared libraries and executables from dependencies (such as .so, .dll, or .dylib files) into a flattened directory structure.

Since Conan 2.20.0, subdirectories are maintained and preserved as-is. Files are only included in environment generators when correctly specified through cpp_info.bindirs and cpp_info.libdirs configuration.

Note

runtime_deploy only copies dependencies whose requirement has the run trait set to True. A static-library dependency is skipped by default, even if it internally ships a shared library needed at runtime. To include such a dependency, declare "run": True inside package_type_traits in its recipe.

cyclone_1.6 and cyclone_1.4

The cyclone_1.6 and cyclone_1.4 deployers are available to generate a CycloneDX 1.6 or 1.4 SBOM file respectively, with the information of the dependencies in the graph. The generated file will be named sbom-cyclonedx-1.{6, 4}.json and it will be located in the deployer output folder. These deployers will use the cyclonedx_1_6 and cyclonedx_1_4 functions from the conan.tools.sbom.cyclonedx module with default arguments.

If you want to customize the generated SBOM, you can either create your own custom deployer that calls these functions with the desired arguments, or use the documented hook approach from the previous link to generate the SBOM.

configuration

The full_deploy, direct_deploy and runtime_deploy understand when the conf tools.deployer:symlinks is set to False to disable deployers copying symlinks. This can be convenient in systems that do not support symlinks and could fail if deploying packages that contain symlinks.

Custom deployers

Custom deployers can be managed via conan config install. When looking for a specific deployer, Conan will look in these locations for the deployer in the following order:

  1. Absolute paths

  2. Relative to cwd

  3. In the [CONAN_HOME]/extensions/deployers folder

  4. As built-in deployers

Conan will look for a deploy() method to call for each installed file. The function signature of your custom deployers should be as follows:

my_custom_deployer.py
def deploy(graph, output_folder: str, **kwargs):

(Note that the arguments are passed as named parameters, so both the graph and output_folder names are mandatory)

The **kwargs is mandatory even if not used, as new arguments can be added in future Conan versions, and those would break if **kwargs is not defined.

You can access your conanfile object with graph.root.conanfile. See ConanFile.dependencies for information on how to iterate over its dependencies.

If you need to run binaries from your build dependencies, the recommended approach is to apply the env from a VirtualBuildEnv, such as:

from conan.tools.env import VirtualBuildEnv

def deploy(graph, output_folder: str, **kwargs):
    venv = VirtualBuildEnv(graph.root.conanfile)
    with venv.vars().apply():
        self.run("mytool")

Your custom deployer can now be invoked as if it were a built-in deployer using the filename in which it’s found, in this case conan install . --deployer=my_custom_deployer. Note that supplying the .py extension is optional.

See the custom deployers section for examples on how to implement your own deployers.