Modules and the PowerShell Gallery

Analogy categoryAnalogies

What Is a PowerShell Module?

A module is a self-contained package of PowerShell functions, cmdlets, variables, and resources that can be imported into a session to extend its capabilities. Modules can be a single .psm1 script module, a compiled .dll binary module, or a manifest module described by a .psd1 file that ties multiple pieces together with metadata like version, author, and required dependencies. Organizing code into modules lets you reuse logic across scripts instead of copy-pasting functions everywhere.

🏏

Cricket analogy: A module is like a franchise's full squad list submitted to the IPL auction committee — one manifest (.psd1) declares every player (function), their role, and eligibility, rather than fielding players ad hoc each match.

Discovering and Installing from the PowerShell Gallery

The PowerShell Gallery (powershellgallery.com) is the official public repository for community and Microsoft-published modules, scripts, and DSC resources. The PowerShellGet module provides Find-Module, Install-Module, and Update-Module cmdlets to search the gallery, pull down packages, and keep them current. Modern setups increasingly use the newer Microsoft.PowerShell.PSResourceGet module (Install-PSResource) which is faster and supports additional repository types, but PowerShellGet remains the default on most installed systems.

🏏

Cricket analogy: Find-Module is like searching ESPNcricinfo's player database for a leg-spinner under 25 before the auction — you filter by criteria before committing, exactly as Find-Module -Name Az filters before Install-Module downloads it.

powershell

# Search the Gallery for modules related to Azure
Find-Module -Name Az.* -Repository PSGallery | Select-Object Name, Version

# Install a specific module for the current user only
Install-Module -Name Az -Scope CurrentUser -Repository PSGallery -Force

# Check installed modules and update if newer versions exist
Get-InstalledModule -Name Az
Update-Module -Name Az

# Newer PSResourceGet equivalent
Install-PSResource -Name Az -Scope CurrentUser -TrustRepository

Use -Scope CurrentUser when installing modules on shared or corporate machines you don't administer — it installs to your user profile path without requiring elevated (admin) privileges.

Publishing and Managing Your Own Modules

To publish a module you author yourself, you first scaffold a module manifest with New-ModuleManifest, which generates the .psd1 file describing the module's version, author, exported functions, and required dependencies (RequiredModules). Once your .psm1 and .psd1 are in place inside a correctly named folder, you register an API key from your PowerShell Gallery account and run Publish-Module to upload it. Semantic versioning (Major.Minor.Patch) is expected, and every published version is immutable — you cannot overwrite an existing version, only publish a new one.

🏏

Cricket analogy: Publishing a module is like registering a new player with the BCCI before they can appear in a league — once their registration ID for a season is filed, it can't be silently changed, only superseded next season, mirroring immutable Gallery versions.

powershell

# Scaffold a new module manifest
New-ModuleManifest -Path .\MyTools\MyTools.psd1 `
  -RootModule 'MyTools.psm1' `
  -ModuleVersion '1.0.0' `
  -Author 'Jane Admin' `
  -FunctionsToExport @('Get-DiskReport','Send-AlertEmail')

# Publish to the Gallery (API key from your Gallery account settings)
Publish-Module -Path .\MyTools -NuGetApiKey $env:GALLERY_API_KEY -Repository PSGallery

Published versions on the PowerShell Gallery are permanent and cannot be deleted or overwritten — only unlisted. Test thoroughly with a pre-release tag (e.g. 1.0.0-beta1) before publishing a stable version number.

A module packages functions, variables, and resources with a .psd1 manifest describing metadata and dependencies.
The PowerShell Gallery is the default public repository, searched and installed via Find-Module/Install-Module (PowerShellGet) or Install-PSResource (PSResourceGet).
Use -Scope CurrentUser to install modules without administrator rights.
New-ModuleManifest scaffolds the .psd1 file needed before publishing.
Publish-Module uploads a module using an API key generated from your Gallery account.
Published module versions are immutable — new fixes require a new semantic version, not an overwrite.
RequiredModules in the manifest declares dependencies so consumers automatically get prerequisites installed.