Skip to content

Rework of Package Internalizer documentation #1217

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

Draft
wants to merge 3 commits into
base: master
Choose a base branch
from
+23 −92
Draft

Rework of Package Internalizer documentation #1217

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
61cb667
Rework of Package Internalizer documentation
imm0rtalsupp0rt Sep 4, 2025
d02d91a
Merge branch 'master' into docs-1210
imm0rtalsupp0rt Sep 29, 2025
cb6ac07
(maint) Changed xref title
imm0rtalsupp0rt Sep 29, 2025
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
115 changes: 23 additions & 92 deletions src/content/docs/en-us/features/package-internalizer.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,117 +8,48 @@ import Callout from '@choco-astro/components/Callout.astro';
import Iframe from '@choco-astro/components/Iframe.astro';
import Xref from '@components/Xref.astro';

Automatically Internalize/Recompile Existing Packages (Business and MSP Editions Only)
<div class="card card-body card-border-top pt-c2">
<center>
<p class="h3">Available In:</p>
<p class="mb-0">
Chocolatey for Business
</p>
</center>
</div>

There are thousands of existing packages on the [Chocolatey Community Repository](https://community.chocolatey.org/packages) that are a tremendous resource when it comes to creating packages that have software that can sometimes be tricky! Unfortunately you may be wary of using those packages without changes because many of those packages are subject to distribution rights and thus have an internet dependency (which creates both <Xref title="trust and control issues" value="community-packages-disclaimer" />). There is a process for downloading and internalizing packages to use internal or embedded locations for that software that is called **internalizing** (also known as recompiling).
## Summary
Chocolatey has over 10,000 packages already built and available on the [Chocolatey Community Repository](https://community.chocolatey.org/packages). If you want to put those packages to use in your organization, look no further than **Package Internalizer**!

Chocolatey for Business is able to automatically download packages and resources, edit the scripts, and recompile packages to internalize and remove internet dependencies from those packages, saving you hours of time in <Xref title="manually internalizing/recompiling packages" value="recompile-packages" />!
Many of those packages are subject to distribution rights and thus have an internet dependency (which creates both <Xref title="trust and control issues" value="community-packages-disclaimer" />). **Internalizing** is the process for downloading those packages for use with internal or embedded locations for the software (this may also be referred to as 'recompiling').

## Usage
Package Internalizer can:

Call `choco download` with options including the name of an existing package for Chocolatey for Business to download and download all existing remote resources.
* Be fully scripted and used directly in the command line.
* Control dependency resolution for packages needing additional software to function.
* Internalize specific versions of packages.
* Integrate with automation engines such as Jenkins, GitHub Actions, GitLab CI, Azure DevOps, and more.

![Internalize Existing Packages, Recompiling Resources - if you are on https://docs.chocolatey.org/en-us/guides/create/recompile-packages, see commented html below for detailed description of image](https://img.chocolatey.org/docs/features/features_recompile_packages.png)

{/*
Text in the image above:

Reuse Existing Packages - Automatic Download and Internalize Support

- Chocolatey for Business allows you to take advantage of thousands of existing packages without a dependency on the internet!
- Downloads an existing package and all remote resources.
- Recompiles the package to use those internal resources.
- Optionally can download and point to another location.
- Host recompiled packages on your private internal repositories!

This image shows running `choco download --recompile git.install`.

*/}
Package Internalizer is able to automatically download packages and resources, edit the scripts, remove internet dependencies, and then recompile the packages, saving you hours of time in <Xref title="manually internalizing/recompiling packages" value="recompile-packages" />!

## See It In Action

![automatic recompile](https://img.chocolatey.org/docs/gifs/choco_business_features_recompile.gif)

<Callout type="info">
See all the [feature videos for Chocolatey for Business](https://chocolatey.org/resources/features#c4b).
</Callout>

## Options and Switches

When running `choco download` in the Business editions, pass the following:

```powershell
--outputdirectory=VALUE
OutputDirectory - Specifies the directory for the downloaded Chocolatey
package file. If not specified, uses the current directory.

-i, --ignoredependencies, --ignore-dependencies
IgnoreDependencies - Ignore dependencies when installing package(s).
Licensed editions v1.9.0+ Defaults to false.

--recompile, --internalize
Recompile / Internalize - Download all external resources and recompile
the package to use the local resources instead. Business editions only
(licensed version 1.5.0+).

--resources-location=VALUE
Resources Location - When internalizing, use this location for resources
instead of embedding the downloaded resources into the package. Can be a
file share or an internal url location. When it is a file share, it will
attempt to download to that location. When it is an internal url, it
will download locally and give further instructions on where it should
be uploaded to match package edits. Business editions only (licensed
version 1.5.1+).

--download-location=VALUE
Download Location - OPTIONAL - when internalizing, download the
resources to this location. Used with Resources Location (and defaults
to Resources Location when not set). Business editions only (licensed
version 1.8.3+).

--append-useoriginallocation, --append-use-original-location
Append -UseOriginalLocation - When `Install-ChocolateyPackage` is
internalized, append the `-UseOriginalLocation` parameter to the
function. Business editions only (licensed version 1.7.0+). Requires at
least Chocolatey v0.10.1 for `Install-ChocolateyPackage` to recognize
the switch appropriately. Overrides the feature
'internalizeAppendUseOriginalLocation' set to by default to 'False'.
```

See <Xref title="download command" value="choco-command-download" /> for more information.

## Resources

Community posts that include Package Internalizer:

* [Getting Started With Chocolatey 4 Business & Jenkins CI](https://blog.pauby.com/post/getting-started-with-chocolatey-and-jenkins/)
* [Automating Chocolatey package internalizing with PowerShell](https://winsysblog.com/2017/10/automating-chocolatey-package-internalizing-with-powershell.html) ([archive.org](https://web.archive.org/web/20201025112142/https://winsysblog.com/2017/10/automating-chocolatey-package-internalizing-with-powershell.html))
* [Recompiling Chocolatey packages](https://winsysblog.com/2017/08/recompiling-chocolatey-packages.html) ([archive.org](https://web.archive.org/web/20210815015512/https://winsysblog.com/2017/08/recompiling-chocolatey-packages.html))
Package Internalizer is a powerful asset for any organization. The short video below shows how to put it to work for you!

## FAQ

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

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

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

You can run `choco download` and point it to an existing package name on any remote resource, typically folks point to `https://community.chocolatey.org/api/v2/` and let Chocolatey do all of the work of getting the package and remote resources to recompile the package.

### How does it work?

It downloads a package locally. Then it looks at the install script to determine if there are remote resources, which are downloaded to a directory in the package (or with another switch will be placed on a file share or setup for an http location). Then it edits the install script to use the local resources instead and recompiles the package. The process takes about as long as it takes to download the remote resources.
It downloads a package locally, then it looks at the install script to determine if there are remote resources which are downloaded to a directory in the package (or placed on a file share or setup for an HTTP location; this can be changed with a switch). It then edits the install script to use the local resources and recompiles the package. The process takes about as long as it takes to download the remote resources.

### Does it work with all types of packages?

Some packages are already internalized or don't have remote resources. In those cases it will just download the existing package and have it available for pushing to an internal repository.

### It was not able to download a resource. Why not?

This feature is able to download/recompile quite a few packages. There are a few that it may have issues with, especially if variables with methods are used (e.g. `$(somevar).Replace(".","")`). In those cases it attempts to warn you ahead of time that it cannot handle those yet.

Future versions of the licensed edition will support advanced scenarios such as these.
There are a few resources that it may have issues with, especially if variables with methods are used (e.g. `$(somevar).Replace(".","")`). In those cases it attempts to warn you ahead of time that it cannot handle those yet. Future versions of the licensed edition will support advanced scenarios such as these.

### Are all packages guaranteed to be compatible?

Unfortunately not all packages on the Chocolatey Community Repository are created equal, even with the rigorous moderation process. A few packages do not use the built-in functions for acquiring files from the internet, so they don't lend well to automatic recompiling. Typically Chocolatey will let you know when this is the case and allow you to inspect the package to allow you to finish up the next steps of recompiling. As a future enhancement, it's possible this scenario would also be supported, although it is a very small subset of packages that are created in this way.
Unfortunately, not all packages on the Chocolatey Community Repository are created equal, even with the rigorous <Xref title="moderation process" value="moderation" />.

Typically, Chocolatey will let you know when a package does not use built-in functions for acquiring files from the internet, and will allow you to inspect the package to finish up the next steps of internalization. Although a small subset of packages are created in this way, this scenario may be supported in a future enhancement.