On this page

Publishing PowerShell Modules: Complete Guide

Updated on June 23, 2026

Enrico Hochkoeppler Profile

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:

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:

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:

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​

  1. Go to https://www.powershellgallery.com/.
  2. Sign in with a Microsoft account (Outlook, Live, or Azure AD).
  3. 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:

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!

Buy Me a Coffee

Previous

Creating Modules

Next

Desired State Configuration (DSC)