- Courses
- đź’»Programming Languages
- 🪟PowerShell
- PowerShell Scripting at Scale
- Modules & Packaging
- Publishing Modules
On this page
Publishing PowerShell Modules: Complete Guide
Updated on June 23, 2026
By Enrico Hochkoeppler
Web Developer & TutoriaLibre Founder
Publishing a PowerShell module transforms it from a local script collection into a reusable, versioned, and distributable package. Whether you choose a private repository for internal enterprise use or the public PowerShell Gallery for community sharing, the process relies on the same core tools and concepts: a properly prepared module manifest (.psd1), semantic versioning, and the Publish-Module cmdlet. Private repositories offer complete control over access, security, and lifecycle management, making them ideal for enterprise automation. The PowerShell Gallery provides global visibility and collaboration for open-source projects. Mastering module publishing is a key milestone for any professional PowerShell developer, enabling scalable automation across teams and organizations.
Understanding PowerShell Repositories​
A PowerShell repository is a package source that stores modules in a structured format, allowing PowerShellGet to discover, install, update, and publish modules. Repositories can be file shares, NuGet servers, or cloud-based feeds.
PowerShellGet provides commands to interact with repositories:
Find-Module— searches for modulesInstall-Module— downloads and installs modulesPublish-Module— uploads a module to a repositoryUpdate-Module— updates an installed moduleRegister-PSRepository— registers a new repositoryGet-PSRepository— lists registered repositories
There are two main types of repositories.
PowerShell Gallery (Public)​
The PowerShell Gallery is the default public repository, accessible at https://www.powershellgallery.com/. It is the central hub for open-source PowerShell modules and scripts. Publishing here makes your module available to the entire community, fostering collaboration and reuse. It requires a free Microsoft account and an API key for authentication.
Private Repositories​
Private repositories are hosted internally and are essential for enterprise environments where access control, security, and compliance are critical. They can be implemented using:
- File shares — simple NuGet-compatible folder structures
- NuGet servers — such as ProGet, Azure Artifacts, JFrog Artifactory, or Sonatype Nexus
- GitHub Packages — as a NuGet feed
Private repositories give you full control over who can publish, install, and update modules, and they keep your intellectual property within the organization.
Preparing Your Module for Publishing​
Before publishing, your module must meet several requirements to ensure a smooth release.
Have a Manifest (.psd1)​
A module manifest is mandatory for publishing. It contains metadata that describes the module, its version, author, dependencies, and exported members.
Create a manifest with:
New-ModuleManifest -Path "C:\Modules\MyModule\MyModule.psd1" `
-RootModule "MyModule.psm1" `
-ModuleVersion "1.0.0" `
-Author "Your Name" `
-Description "Provides automation functions for system maintenance."
Code explanation: The New-ModuleManifest cmdlet generates a PowerShell data file (.psd1). The -RootModule points to the main script module. -ModuleVersion sets the initial version. -Author and -Description provide user-facing information. This file is required for publishing and also enables versioning and dependency management.
Follow the Correct Folder Structure​
The module folder must have the same name as the module and contain at least the .psm1 and .psd1 files. A typical structure:
MyModule
│
├── MyModule.psm1
├── MyModule.psd1
├── Public
│ └── Get-Something.ps1
└── Private
└── Helper.ps1
Code explanation: The root folder name MyModule matches the module name. The .psm1 file contains the script logic or dot-sources public and private functions. The .psd1 manifest provides metadata. The Public and Private subfolders help organize code and maintain encapsulation.
Have a Version Number​
The ModuleVersion in the manifest must be a valid semantic version (e.g., 1.0.0, 2.1.3). Increment the version for every release. Semantic versioning uses:
- Major version — breaking changes (e.g.,
2.0.0) - Minor version — new features (e.g.,
1.1.0) - Patch version — bug fixes (e.g.,
1.0.1)
You can also use prerelease suffixes like -beta or -rc1 for unstable versions.
Export Only Intended Functions​
In your manifest, explicitly list the functions to export using FunctionsToExport. Avoid wildcards:
FunctionsToExport = @('Get-Something', 'Set-Something')
Code explanation: This ensures that only intended functions are exposed to users. Omitting this or using * can expose internal helper functions, breaking encapsulation and creating a confusing API surface.
Include Comment-Based Help​
Every exported function should have comment-based help (.SYNOPSIS, .DESCRIPTION, .PARAMETER, .EXAMPLE). This is essential for user experience and professional credibility. The PowerShell Gallery displays help content, and users rely on Get-Help to understand your module.
Publishing to a Private Repository​
Private repositories are common in enterprise settings. The process involves registering the repository, publishing the module, and then installing it from the same source.
Register the Private Repository​
Before publishing, you must register the repository using Register-PSRepository. This tells PowerShell where to find and publish modules.
Example: registering a file-share repository
Register-PSRepository `
-Name "InternalRepo" `
-SourceLocation "\\Server\PSRepo" `
-PublishLocation "\\Server\PSRepo" `
-InstallationPolicy Trusted
Code explanation: -Name is a friendly name for the repository. -SourceLocation and -PublishLocation point to the same folder path. -InstallationPolicy Trusted suppresses prompts when installing from this repository, which is useful in automated environments.
Example: registering a NuGet-based repository (e.g., ProGet, Azure Artifacts)
Register-PSRepository `
-Name "InternalNuGet" `
-SourceLocation "https://nuget.contoso.com/api/v2" `
-PublishLocation "https://nuget.contoso.com/api/v2/package" `
-InstallationPolicy Trusted
Code explanation: -SourceLocation is the NuGet API endpoint for discovering modules. -PublishLocation is the endpoint for uploading packages. Some NuGet servers require separate endpoints for publishing.
Publish the Module​
Once the repository is registered, publish the module using Publish-Module:
Publish-Module -Name "MyModule" -Repository "InternalRepo"
If the repository requires authentication (e.g., NuGet API key, username/password):
$cred = Get-Credential
Publish-Module -Name "MyModule" -Repository "InternalRepo" -Credential $cred
Code explanation: -Name is the module name (matching the folder name). -Repository is the registered repository name. If a NuGet API key is needed, you can pass it with -NuGetApiKey. The Publish-Module cmdlet packages the module into a .nupkg file and uploads it to the repository.
Installing from the Private Repository​
Users can install the module from the private repository:
Install-Module -Name "MyModule" -Repository "InternalRepo"
To update to the latest version:
Update-Module -Name "MyModule"
Code explanation: Install-Module searches the specified repository and installs the module into the user's module path. If multiple versions exist, the latest stable version is installed.
Publishing to the PowerShell Gallery​
The PowerShell Gallery is the default public repository. Publishing here requires an account and an API key.
Create a PowerShell Gallery Account​
- Go to https://www.powershellgallery.com/.
- Sign in with a Microsoft account (Outlook, Live, or Azure AD).
- Once signed in, navigate to your profile and generate a new API Key. This key is used to authenticate publishing requests.
Register the Gallery as a Repository​
The Gallery is typically pre-registered as PSGallery. Verify with:
Get-PSRepository
If it is not listed, register it:
Register-PSRepository -Name "PSGallery" -SourceLocation "https://www.powershellgallery.com/api/v2" -InstallationPolicy Trusted
Publish the Module​
Use your API key to publish:
Publish-Module -Name "MyModule" -Repository "PSGallery" -NuGetApiKey "YOUR-API-KEY"
Code explanation: The -NuGetApiKey parameter supplies the API key obtained from the PowerShell Gallery website. This authenticates your publishing request. The module is uploaded and becomes publicly available within minutes.
Updating the Module​
To publish a new version, increment the ModuleVersion in the manifest and republish:
Publish-Module -Name "MyModule" -Repository "PSGallery" -NuGetApiKey "YOUR-API-KEY"
Code explanation: The Gallery uses the version number to track releases. Users can install specific versions using -RequiredVersion or update to the latest with Update-Module.
Best Practices for Publishing​
Following these best practices ensures your modules are professional, reliable, and easy to maintain.
Always Increment the Version Number​
Use semantic versioning and never republish the same version with different content. If you need to fix a bug, increment the patch version. For new features, increment the minor version. For breaking changes, increment the major version.
Include Complete Comment-Based Help​
Every exported function should have a .SYNOPSIS, .DESCRIPTION, .PARAMETER for each parameter, and at least one .EXAMPLE. Good help reduces support requests and builds trust.
Include Tests (Pester)​
Pester is the de facto testing framework for PowerShell. Including tests demonstrates reliability and makes refactoring safer. In enterprise settings, tests are often required before publishing.
Use a Clean Folder Structure​
Separate public and private functions into Public and Private folders. This improves maintainability and clarity, especially as your module grows.
Sign Your Scripts​
In many organizations, script signing is mandatory. Use Set-AuthenticodeSignature to sign your .psm1 and .ps1 files. This assures users that the code comes from a trusted source and hasn't been tampered with.
Avoid Breaking Changes​
Design your functions with stability in mind. If you must introduce a breaking change, increment the major version and document the migration path clearly. This minimizes disruption for your users.
Summary​
Publishing PowerShell modules—whether to a private repository or the public PowerShell Gallery—is a professional practice that enables reusability, versioning, and distribution. The process involves:
- Preparing your module with a manifest (
.psd1), correct folder structure, and semantic versioning - Registering a repository using
Register-PSRepository - Publishing with
Publish-Module - Installing and updating using
Install-ModuleandUpdate-Module
Private repositories provide security and control for enterprise automation, while the PowerShell Gallery fosters open-source collaboration. By following best practices such as explicit function exports, comment-based help, and semantic versioning, you create modules that are trustworthy, easy to use, and maintainable. Mastering module publishing is a key skill for any advanced PowerShell developer.
Found this helpful? Share the knowledge...
... or support this project to keep it alive!
Previous
Creating Modules
Next
Desired State Configuration (DSC)
-
Understanding PowerShell Repositories
- PowerShell Gallery (Public)
- Private Repositories
-
Preparing Your Module for Publishing
- Have a Manifest (
.psd1) - Follow the Correct Folder Structure
- Have a Version Number
- Export Only Intended Functions
- Include Comment-Based Help
- Have a Manifest (
-
Publishing to a Private Repository
- Register the Private Repository
- Publish the Module
- Installing from the Private Repository
-
Publishing to the PowerShell Gallery
- Create a PowerShell Gallery Account
- Register the Gallery as a Repository
- Publish the Module
- Updating the Module
-
Best Practices for Publishing
- Always Increment the Version Number
- Include Complete Comment-Based Help
- Include Tests (Pester)
- Use a Clean Folder Structure
- Sign Your Scripts
- Avoid Breaking Changes
-
Summary
