Skip to content

(#1021) Provide clarity to choco sync command #1324

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
steviecoaster merged 1 commit into from
May 14, 2026
+46 −59
Merged

(#1021) Provide clarity to choco sync command #1324

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 46 additions & 59 deletions src/content/docs/en-us/features/package-synchronization/sync-command.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,96 +8,83 @@ import Callout from '@choco-astro/components/Callout.astro';
import Iframe from '@choco-astro/components/Iframe.astro';
import Xref from '@components/Xref.astro';

## Sync Command
<Callout type="danger">
This feature requires following specific instructions for its recommended use. Please read this documentation before running the `choco sync` command.
</Callout>

Starting in 1.9.0 of the licensed extension, sync has been added as a preview feature for organizations to try out. Currently Business edition only, but expected to be in Pro+ at some point - check https://chocolatey.org/compare#compare for availability.
## Summary

Sync looks at all software that is in Programs and Features that is not being managed with Chocolatey packages and brings them under management. This means you can run one command and suddenly, all of the software installed on a machine is under management by Chocolatey!
When running `choco list --include-programs`, a list of additional applications can be seen at the end of the output that are not managed with Chocolatey.

### Usage
Running the `choco sync` command allows Chocolatey to reference the registry keys for those additional applications in Programs and Features that are not being managed with Chocolatey, automatically generate a package, and then map the application to that package and bring it under Chocolatey's management.

To synchronize your system, Simply call `choco sync` and Chocolatey will ensure that all software in Programs and Features comes under Chocolatey management and provides you the packages/package sources so you can add them to source control for managing those packages over time.
**Use of the `choco sync` command is only available with a Chocolatey for Business (C4B) license.**

#### Setup
Syncing software can be tricky because the _package ID_ (the name of the package) is what Chocolatey uses for management, not the name of the _application_. For example, the package for Google Chrome on the [Chocolatey Community Repository (CCR)](https://community.chocolatey.org/packages/) is named `GoogleChrome`, but running `choco sync` without any options would create and name the package `google-chrome`. The names of packages listed on the CCR versus how Chocolatey may name them automatically can vary, which is why we recommend verifying the package IDs.

At 1.9.0, sync is in preview. You need to turn it on by enabling the feature `allowPreviewFeatures`:
As a result, while the `GoogleChrome` package from the Chocolatey Community Repository and the `google-chrome` package generated by running `choco sync` without options contain the same application, Chocolatey respects them as _two separate packages_ due to the difference in their package IDs. This is why recommended practice is to use the listed options `--id` and `--package-id` to directly map the application to the wanted package ID instead of allowing the package ID to be created by Chocolatey without user input.

* `choco feature enable --name allowPreviewFeatures`
### Recommended Use

### See it in action
To synchronize your system to allow future management with packages from the Chocolatey Community Repository (CCR):

We've prepared a short video to show sync in action:
1. Search for the packages on the Chocolatey Community Repository that correspond with the software that you have listed in Programs and Features. These package IDs can also be used for downloading and hosting packages in your internal repository with <Xref title="Package Internalizer" value="package-internalizer" />, which is how we recommend organizations use the CCR.
2. Open an administrative PowerShell session and run `choco sync --id='SOFTWARE_NAME_IN_PROGRAMS_AND_FEATURES' --package-id='PACKAGE_ID_FROM_CCR'` to map the software directly with the correct package ID.
3. Chocolatey will create the package for the software in Programs and Features. After creation, the package is placed in the directory where the command is run in the `sync` folder by default (for example, if you run the command from `C:\Packages\Chocolatey`, the synced package will be located at `C:\Packages\Chocolatey\sync`), where you can retrieve it and push it to your internal repository. If you specified a directory with the `--output-directory` option, the package will be placed there instead.

[![Chocolatey's Package Synchronizer - Sync Command](https://img.chocolatey.org/docs/features/sync-command-video.png)](https://youtu.be/tzSsYHYsjf4 "Chocolatey's Package Synchronizer - Sync Command")
#### Syncing Multiple Packages with Powershell

<Callout type="info">
To see all feature videos for Chocolatey for Business, please visit https://chocolatey.org/resources/features#c4b.
</Callout>
The code below is an example of using the `choco sync` command to map several applications to specific package IDs with a single use of the command:

In the following image, sync is run on a system that has 18 applications installed and a base Chocolatey for Business install. Note after running sync, all software on the machine is now being managed by Chocolatey.
```PowerShell
$mapping = @{
'Google Chrome' = 'googlechrome'
'Docker Dekstop' = 'docker-desktop'
'Microsoft Visual C++ v14 Redistributable (x64) - 14.50.35719' = 'vcredist140'
'Microsoft Visual Studio Code' = 'vscode'
}

![Chocolatey's Package Synchronizer Sync Command - if you are on https://docs.chocolatey.org/en-us/features/package-synchronization, see commented html below for detailed description of image](https://img.chocolatey.org/docs/features/features_choco_sync.png)
$mapping.GetEnumerator() | Foreach-Object {choco sync --id="$($_.Key)" --package-id="$($_.Value)" }
```

{/*
Text in the image above:
### Alternate Use

Package Synchronizer's Sync Command
To synchronize your system to allow internal management only, open an administrative PowerShell session and run `choco sync` and Chocolatey will automatically create and name packages for all software in Programs and Features. These packages are placed in the `C:\Users\$USERNAME\sync` folder by default, where you can retrieve them and push them to your internal repository. If you specified a directory with the `--output-directory` option, the packages will be placed there instead.

- Brings unmanaged software under Chocolatey management
- Provides you the source packaging and package output
- Automate existing systems in under 90 seconds!
- Machine parseable with `-r`
- Links existing packages not tracking to Programs and Features
### Additional Considerations

This image shows running `choco sync`. It shows first a system that has 18 applications installed outside of Chocolatey, then runs `choco sync` and watches Chocolatey generate packages and baseline the system. Then it shows `choco list -lo --include-programs` again, which shows that all software on the machine is now being managed by Chocolatey.
It is not recommended to run `choco sync` continually over time, such as through a scheduled task or a Chocolatey Central Management deployment. The command is designed to be used once to create a package for an application already installed to remove the need to create that package from the ground up, and going forward, applications should be managed with Chocolatey packages.
Comment thread
imm0rtalsupp0rt marked this conversation as resolved.

*/}
When you use `choco sync`, there may be additional work necessary to make the generated packages viable depending on the type of installer the software uses.

Software installed from an MSI will sync without the need to make further changes. Software installed from an `exe`-based installer, such as `setup.exe`, will need the original installer placed in the `tools` directory inside the package. Additionally, silent arguments will need to be added to the `chocolateyInstall.ps1` for installation and possibly to the `chocolateyUninstall.ps1` for uninstallation. Both the `chocolateyInstall.ps1` and `chocolateyUninstall.ps1` can found in the `tools` directory inside the package.

### Options and Switches

The following are available in the <Xref title="choco sync" value="choco-command-sync" /> command.

```
--id=VALUE
--id=VALUE
Id - The Display Name from Programs and Features

--out, --outdir, --outputdirectory, --output-directory=VALUE
--packageid, --package-id=VALUE
PackageId - When used with Id, this will be the custom name for the
package. Business editions only.

--out, --outdir, --outputdirectory, --output-directory=VALUE
OutputDirectory - Specifies the directory for the generated Chocolatey
package file(s). If not specified, uses a subdirectory of the current
directory.
Comment thread
imm0rtalsupp0rt marked this conversation as resolved.
```
Comment thread
imm0rtalsupp0rt marked this conversation as resolved.

### FAQ

#### How do I take advantage of this feature?

You must have the [business edition of Chocolatey](https://chocolatey.org/pricing). Business editions are great for organizations that need to manage the total software management lifecycle.

#### I'm a business customer, now what?

You would periodically run `choco sync`.
-r, --limitoutput, --limit-output
LimitOutput - Limit the output to essential information. This provides machine parsable output.

#### How does it work?

Chocolatey takes a look at all software in Programs and Features that is not under Chocolatey management, generates packages on the fly and baselines them under the Chocolatey install, ensuring all of the links are tracked.

#### Do I get the packages to add to source?

Yes! Chocolatey will tell you the location of the sync files so you can put them into source control.

#### Some packages have a TODO list

Generating packages on the fly from Programs and Features for non-MSI installers doesn't provide everything necessary to ensure an actual install. So when you take those packages back to source, you will need to finish out the packaging for those so that later when you upgrade, things will work appropriately.

#### How do I get machine parseable output?

Use `-r`. `choco sync -r`.

#### What if I have an existing package that is just not tracking to Programs and Features?

Synchronize can recognize existing packages and sync to those as long as the name of the package is a close match to the software name (e.g. Google Chrome becomes either google-chrome or googlechrome).
--noop, --whatif, --what-if
NoOp / WhatIf - Don't actually do anything.
Comment thread
imm0rtalsupp0rt marked this conversation as resolved.
```

### Sync Command Known issues
## Sync Command Known Issues

* Any packages you've installed side by side (`-m`) will show up every time during sync.
* If you have both a 64-bit and 32-bit version of some software installed, sync will track to one on the first run and the other on the next run. This is not a normal scenario.
* If you have both a 64-bit and 32-bit version of some software installed, sync will track to one on the first run and the other on the next run. This is not a normal scenario.
* If uninstalling a package created from running `choco sync`, the uninstall may not be silent, causing the auto uninstaller to fail. This may or may not result in the package being removed.
Loading