Update-Module 5.0 adds, not updates

February 17th, 2016 by June Blender
Last updated on February 10th, 2016

 

Applies to:

— Windows PowerShell 5.0.10586.63
— PowerShellGet 1.0.0.1


I’m a huge fan of sharing Windows PowerShell modules and making them easy to find (Find-Module), view (Save-Module), and install (Install-Module). So, I truly love the new PowerShellGet module.

However, you really need to understand how it works before you use it. Otherwise, you might end up with commands and modules that don’t work correctly (or at all) or don’t do what you expect. Or, you might download modules with commands that shadow or hide commands that your scripts run.

Update-Module is one of the really useful cmdlets in PowerShellGet, but if you don’t know how it works, it might surprise you. In Windows PowerShell 5.0, Update-Module doesn’t update a module. It adds one.

And, this is important to understand, because when you have side-by-side versions of the same module, you might mistakenly import the wrong version of a module or run the wrong version of a command.

I once made the mistake of piping Get-InstalledModule (all of them) to Update-Module. It took a long time to run and it installed additional versions of many of my modules in my poor, bloated Modules directory.

Here’s how Update-Module works:

  • When you use Update-Module with no version parameters, it checks to see if the newest version of the module is newer than the newest version you have. If it is, it installs the newest version beside the current version in the same directory. Otherwise, it does nothing.
PS C:\> Get-Module -List PowerForensics

Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules
ModuleType Version    Name                  ExportedCommands
---------- -------    ----                  ----------------
Binary     1.0.2      PowerForensics        {ConvertFrom-BinaryData, ConvertTo-ForensicTimeline

PS C:\> Update-Module PowerForensics
PS C:\> Get-Module -List PowerForensics
Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules
ModuleType Version    Name                  ExportedCommands
---------- -------    ----                  ----------------
Binary     1.1.1      PowerForensics        {ConvertFrom-BinaryData, ConvertTo-ForensicTimeline
Binary     1.0.2      PowerForensics        {ConvertFrom-BinaryData, ConvertTo-ForensicTimeline

 

  • When you use Update-Module with the RequiredVersion parameter, it checks to see if the specified version of the module is already installed. If it is not, it installs the specified version beside the current version in the same directory. Otherwise, it does nothing.In this example, I use -RequiredVersion to install an earlier version of the module.

 

PS C:\> Get-Module -List xJea

    Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules

ModuleType Version    Name        ExportedCommands
---------- -------    ----        ----------------
Manifest   0.2.10     xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...

PS C:\> Update-Module xJea -RequiredVersion 0.2.9
PS C:\> Get-Module -List xJea

    Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules

ModuleType Version    Name        ExportedCommands
---------- -------    ----        ----------------
Manifest   0.2.10     xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...
Manifest   0.2.9      xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...
  • When you use Update-Module with the MaximumVersion parameter, it determines whether it has a version equal to or greater than the specified version. If it does and if (IFF) the selected version is newer than the newest version of the module that is installed, it installs the selected version beside the current version in the same directory. Otherwise, it does nothing.
PS C:\> Get-Module -List xJea

    Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules

ModuleType Version    Name        ExportedCommands
---------- -------    ----        ----------------
Manifest   0.2.10     xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...
Manifest   0.2.9      xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...

PS C:\> Find-Module -Name xJea -RequiredVersion 0.2.8

Version    Name      Type       Repository           Description
-------    ----      ----       ----------           -----------
0.2.8      xJea      Module     PSGallery            Module with DSC Resources f


PS C:\> Update-Module -Name xJea -MaximumVersion 0.2.8
PS C:\> Get-Module -List xJea

    Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules

ModuleType Version    Name        ExportedCommands
---------- -------    ----        ----------------
Manifest   0.2.10     xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...
Manifest   0.2.9      xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}...

PS C:\> Update-Module -Name xJea -MaximumVersion 0.2.11
PS C:\> Get-Module -List -Name xJea

    Directory: C:\Users\JuneB\Documents\WindowsPowerShell\Modules

ModuleType Version    Name        ExportedCommands
---------- -------    ----        ----------------
Manifest   0.2.11     xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}
Manifest   0.2.10     xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}
Manifest   0.2.9      xJea        {Show-JeaPresentation, show-JeaWhitePaper, Show-JeaExamples}
  • With the Force parameter, Update-Module skips all checks for versions currently installed on the computer. As a result, with -Force, Update-Module actually updates, that is, replaces, the specified version of the module if it’s already installed on the computer. If the requested version is not installed, Update-Module installs it, even if it’s older than an currently installed version.
PS C:\> Update-Module -Name xJea -RequiredVersion 0.2.10 -Verbose
VERBOSE: Checking for updates for module 'xJea'.
VERBOSE: Repository details, Name = 'PSGallery', Location = 'https://www.powershellgallery.co
IsRegistered = 'True'.
VERBOSE: Using the provider 'PowerShellGet' for searching packages.
VERBOSE: Using the specified source names : 'PSGallery'.
VERBOSE: Getting the provider object for the PackageManagement Provider 'NuGet'.
VERBOSE: The specified Location is 'https://www.powershellgallery.com/api/v2/' and PackageMan
VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id
VERBOSE: Total package yield:'1' for the specified package 'xJea'.
VERBOSE: Skipping installed module xJea 0.2.10.

PS C:\> Update-Module -Name xJea -RequiredVersion 0.2.10 -Verbose -Force
VERBOSE: Checking for updates for module 'xJea'.
VERBOSE: Repository details, Name = 'PSGallery', Location = 'https://www.powershellgallery.co
IsRegistered = 'True'.
VERBOSE: Using the provider 'PowerShellGet' for searching packages.
VERBOSE: Using the specified source names : 'PSGallery'.
VERBOSE: Getting the provider object for the PackageManagement Provider 'NuGet'.
VERBOSE: The specified Location is 'https://www.powershellgallery.com/api/v2/' and PackageMan
VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id
VERBOSE: Total package yield:'1' for the specified package 'xJea'.
VERBOSE: Performing the operation "Update-Module" on target "Version '0.2.10' of module 'xJea
VERBOSE: The installation scope is specified to be 'CurrentUser'.
VERBOSE: The specified module will be installed in 'C:\Users\JuneBlender\Documents\WindowsPow
VERBOSE: The specified Location is 'NuGet' and PackageManagementProvider is 'NuGet'.
VERBOSE: Downloading module 'xJea' with version '0.2.10' from the repository 'https://www.pow
VERBOSE: Searching repository 'https://www.powershellgallery.com/api/v2/FindPackagesById()?id
VERBOSE: InstallPackage' - name='xJea', version='0.2.10',destination='C:\Users\JuneBlender\Ap
VERBOSE: DownloadPackage' - name='xJea',
version='0.2.10',destination='C:\Users\JuneBlender\AppData\Local\Temp\1556275497\xJea\xJea.nu
uri='https://www.powershellgallery.com/api/v2/package/xJea/0.2.10'
VERBOSE: Downloading 'https://www.powershellgallery.com/api/v2/package/xJea/0.2.10'.
VERBOSE: Completed downloading 'https://www.powershellgallery.com/api/v2/package/xJea/0.2.10'
VERBOSE: Completed downloading 'xJea'.
VERBOSE: InstallPackageLocal' - name='xJea', version='0.2.10',destination='C:\Users\JuneBlend
VERBOSE: Module 'xJea' was installed successfully.

 

If you’re worried about side-by-side versions, you can use the Get-InstalledModule and Uninstall-Module cmdlets to uninstall all older versions.

PS C:\> Get-InstalledModule -Name xJea -AllVersions

Version    Name         Type       Repository           Description
-------    ----         ----       ----------           -----------
0.2.10     xJea         Module     PSGallery            Module with DSC
0.2.11     xJea         Module     PSGallery            Module with DSC
0.2.8      xJea         Module     PSGallery            Module with DSC
0.2.9      xJea         Module     PSGallery            Module with DSC

PS C:\> Get-InstalledModule -Name xJea -AllVersions | 
           Sort Version -Descending | 
           Select-Object -Skip 1 | 
           Uninstall-Module

PS C:\> Get-InstalledModule -Name xJea -AllVersions

Version    Name       Type       Repository           Description
-------    ----       ----       ----------           -----------
0.2.11     xJea       Module     PSGallery            Module with DSC Resources for Just Enough Ad

 

So, how does Update-Module differ from the Install-Module cmdlet?

  •  It install only newer versions of the module (without -Force).
  •  It always installs its versions of the module in the same directory. It doesn’t not have a Scope or Path parameter.
  •  It does not have a MinimumVersion parameter.
  •  None of the parameters have a Version alias. In the Import-Module, Find-Module, Save-Module, and Install-Module cmdlets, -Version is an alias for the MinimumVersion parameter.

And, just to make things interesting, the new Update-Script cmdlet actually updates the specified script. It does not install a newer version of the script in the same directory or in a versioned subdirectory.

In summary, Update-Module is great, but you need to understand how it works.

June Blender is a technology evangelist at SAPIEN Technologies, Inc. and a Windows PowerShell MVP. You can reach her at juneb@sapien.com and follow her on Twitter at @juneb_get_help.

 

 
[Google+]   [Facebook]   [LinkedIn]   [StumbleUpon]   [Digg]   [Reddit]   [Google Bookmark]  

Tags: , , , , , ,