Import-Module nie znajduje modułu

Import-Module nie znajduje modułu PowerShell wskazuje, że moduł nie znajduje się w żadnej ze ścieżek zdefiniowanych w zmiennej PSModulePath — trzeba go zainstalować lub wskazać pełną ścieżkę.

Import-Module nie znajduje modułu – co oznacza ten komunikat

Komunikat Import-Module informujący o braku modułu oznacza, że PowerShell nie potrafi odnaleźć wskazanego pakietu w lokalizacjach przeznaczonych do wyszukiwania modułów. Polecenie może być zapisane poprawnie, a mimo to nie zadziałać, jeżeli nazwa modułu nie odpowiada nazwie katalogu, moduł nie został zainstalowany albo jego folder nie znajduje się w zmiennej środowiskowej PSModulePath. W takiej sytuacji PowerShell nie ma informacji, skąd załadować polecenia, funkcje, aliasy lub inne elementy udostępniane przez dany moduł.

Nie zawsze oznacza to uszkodzenie samego PowerShella. Często problem dotyczy różnicy między nazwą używaną w dokumentacji a nazwą faktycznie zainstalowanego modułu, niewłaściwego zakresu instalacji albo uruchomienia konsoli w innym środowisku użytkownika. Znaczenie może mieć również to, czy używana jest klasyczna konsola Windows PowerShell, czy nowsza wersja PowerShell. Oba środowiska mogą korzystać z innych lokalizacji, profili i zestawów dostępnych modułów.

Warto odróżnić brak modułu od błędu występującego już podczas jego ładowania. Jeśli PowerShell nie widzi modułu, zwykle pojawia się informacja o niemożności znalezienia określonego modułu lub pliku. Jeżeli moduł zostanie odnaleziony, ale nie może zostać uruchomiony z powodu brakującej zależności, niezgodnej wersji albo błędu w pliku manifestu, komunikat będzie miał inną treść. Rozróżnienie tych przypadków ułatwia dobranie właściwego sposobu naprawy.

Jak PowerShell wyszukuje moduły i gdzie powstaje różnica

Podczas wykonywania Import-Module PowerShell sprawdza lokalizacje zapisane w zmiennej PSModulePath. Zawiera ona listę katalogów oddzielonych odpowiednim separatorem dla danego systemu. W tych miejscach powinny znajdować się podkatalogi odpowiadające nazwom modułów, a wewnątrz nich pliki modułu, takie jak skrypt .psm1, biblioteka binarna lub manifest .psd1. Jeżeli katalog został utworzony poza zdefiniowanymi ścieżkami, samo istnienie pliku na dysku nie wystarczy do automatycznego odnalezienia go przez PowerShell.

Przydatnym sprawdzeniem jest odczyt aktualnych ścieżek:

$env:PSModulePath -split [IO.Path]::PathSeparator

Do sprawdzenia, czy moduł jest widoczny dla bieżącej sesji, można użyć:

Get-Module -ListAvailable -Name NazwaModulu

Brak wyniku sugeruje, że moduł nie znajduje się w żadnej z aktualnie przeszukiwanych lokalizacji albo jego nazwa została podana nieprawidłowo. Jeżeli moduł jest dostępny, można sprawdzić jego dokładną lokalizację oraz wersję:

Get-Module -ListAvailable -Name NazwaModulu |
    Select-Object Name, Version, ModuleBase

W przypadku modułu zainstalowanego z galerii PowerShell często stosuje się instalację dla bieżącego użytkownika lub dla całego systemu. Wybrany zakres wpływa na miejsce zapisania plików i na to, czy moduł będzie widoczny dla innych kont. Przykładowe polecenie instalacyjne powinno być dopasowane do rzeczywistej nazwy pakietu:

Install-Module -Name NazwaModulu -Scope CurrentUser

Jeżeli moduł znajduje się w niestandardowym katalogu, można tymczasowo wskazać pełną ścieżkę do pliku lub katalogu. Takie rozwiązanie bywa pomocne przy testowaniu, ale w środowisku używanym regularnie lepiej uporządkować instalację i ścieżki, aby skrypt nie zależał od jednego komputera ani konkretnego położenia plików. Przydatne może być także sprawdzenie, czy polecenie jest uruchamiane w tej samej sesji, w której zmieniono PSModulePath, ponieważ niektóre zmiany wymagają ponownego otwarcia konsoli.

Warto sprawdzić również sposób zapisu nazwy. Nazwa modułu używana przy Import-Module może różnić się od nazwy pojedynczego polecenia udostępnianego przez moduł. Na przykład obecność polecenia o określonym prefiksie nie musi oznaczać, że dokładnie taki sam tekst jest nazwą modułu. Pomocne bywają polecenia:

Get-Command -Module NazwaModulu
Get-Module -ListAvailable

Jeżeli moduł jest załadowany, lecz polecenia nadal nie są dostępne, należy sprawdzić eksportowane funkcje, aliasy i cmdlety oraz ewentualne warunki zapisane w manifeście. W takiej sytuacji problem nie dotyczy już samego wyszukiwania modułu, lecz jego zawartości albo sposobu eksportowania elementów.

Typowe przyczyny błędu Import-Module

Jedną z częstszych przyczyn jest brak instalacji pakietu. Dotyczy to szczególnie skryptów kopiowanych z dokumentacji, które zakładają wcześniejsze przygotowanie środowiska. Przed instalacją należy ustalić prawidłową nazwę modułu, źródło pochodzenia oraz wymagania dotyczące wersji PowerShell. Instalowanie przypadkowego pakietu o podobnej nazwie może nie rozwiązać problemu i może wprowadzić dodatkowe zależności.

Inny przypadek stanowi instalacja modułu w zakresie niedostępnym dla bieżącego użytkownika. Moduł może być zapisany w profilu administratora, podczas gdy skrypt działa na zwykłym koncie, albo odwrotnie. Różnicę można zauważyć, porównując wynik Get-Module -ListAvailable uruchomiony w różnych sesjach. Znaczenie ma też uruchomienie PowerShella w podwyższonym kontekście, ponieważ zmiana konta może oznaczać zmianę profilu, zmiennych środowiskowych i widocznych katalogów.

Błąd może pojawić się po ręcznym przeniesieniu folderu modułu. Jeżeli struktura katalogów nie odpowiada oczekiwaniom PowerShella, moduł nie zostanie rozpoznany mimo obecności pliku .psm1. Problemem bywa również dodatkowy poziom katalogu, zmiana nazwy folderu, pozostawienie kilku niekompletnych kopii albo usunięcie pliku manifestu, gdy moduł wymaga jego obecności. Przed modyfikacją warto ustalić, czy używany jest moduł skryptowy, binarny, czy oparty na manifeście.

W środowisku zawierającym kilka wersji tego samego modułu może zostać wybrana inna wersja niż oczekiwana przez skrypt. Niektóre polecenia wymagają konkretnego interfejsu lub zależności i nie działają ze starszym wydaniem. Wersję można wskazać jawnie, jeśli dokumentacja danego modułu tego wymaga:

Import-Module -Name NazwaModulu -RequiredVersion Wersja

Trzeba jednak użyć prawidłowej wartości odpowiadającej wersji faktycznie dostępnej na komputerze. Jeżeli moduł ładuje się, ale zgłasza błąd zależności, należy sprawdzić jego wymagania, dostępność powiązanych bibliotek oraz zgodność architektury używanej sesji z modułem binarnym. Nie każdy problem z załadowaniem można naprawić samą zmianą PSModulePath.

Znaczenie może mieć także profil PowerShell, w którym ustawiono własne aliasy, zmienne lub modyfikacje ścieżek. Skrypt działający w jednej konsoli może nie działać w nowej sesji, jeżeli potrzebne ustawienia były wprowadzone ręcznie i nie zapisano ich w profilu. Przy diagnozie warto porównać wynik poleceń w zwykłej sesji oraz w sesji uruchomionej bez profilu, aby ustalić, czy przyczyna leży w konfiguracji użytkownika.

Oddzielnej uwagi wymaga polityka wykonywania skryptów. Może ona blokować uruchomienie pliku modułu, ale zwykle daje komunikat o zablokowanym skrypcie, a nie o całkowitym braku modułu. Dlatego nie należy zmieniać ustawień bezpieczeństwa w ciemno. Najpierw trzeba ustalić dokładny tekst błędu, źródło modułu oraz zakres zmiany, która miałaby zostać wprowadzona.

Kiedy najlepiej poprosić o ocenę stanu sprzętu - Import-Module nie znajduje modułu

Do serwisu warto zgłosić się wtedy, gdy moduł powinien być zainstalowany, ale PowerShell nadal go nie widzi, problem występuje po zmianie systemu lub konta użytkownika, albo błąd pojawia się tylko w określonych skryptach. Szczególnie pomocna jest konsultacja, gdy nie wiadomo, czy przyczyną jest brak pakietu, nieprawidłowa ścieżka, konflikt wersji, uszkodzona instalacja czy ograniczenia uprawnień. Przed przekazaniem komputera dobrze zachować pełny komunikat błędu, nazwę używanego modułu oraz polecenie, które go wywołuje.

W Warszawie takie przypadki można przekazać do Warszawskiego Pogotowia Komputerowego 24/7, gdzie diagnoza laptopa jest darmowa. Podczas sprawdzania analizowana jest konfiguracja PowerShella, widoczność modułu w bieżącym profilu, zawartość wskazanych katalogów oraz zgodność instalacji z używaną wersją środowiska. Pozwala to oddzielić problem z samym modułem od szerszych kłopotów z profilem użytkownika, uprawnieniami lub konfiguracją systemu.

Przy zgłoszeniu warto opisać, czy błąd występuje przy każdym uruchomieniu, czy tylko podczas wykonywania konkretnego skryptu. Przydatne mogą być także informacje o tym, czy moduł był instalowany ręcznie, przez galerię PowerShell, razem z innym programem lub po aktualizacji systemu. Jeżeli problem pojawił się po przeniesieniu danych, zmianie konta albo odtworzeniu systemu z kopii, należy zaznaczyć ten fakt, ponieważ wskazuje on na możliwą zmianę lokalizacji plików i zmiennych środowiskowych.

Nie zaleca się usuwania wszystkich katalogów modułów ani szerokiego modyfikowania zmiennej PSModulePath bez kopii ustawień. Takie działania mogą ukryć właściwą przyczynę i spowodować, że inne skrypty przestaną działać. Bezpieczniejsza diagnostyka polega na ustaleniu nazwy modułu, sprawdzeniu jego dostępności poleceniem Get-Module -ListAvailable, porównaniu ścieżek oraz dopiero późniejszej naprawie brakującego elementu. Dzięki temu można przywrócić działanie importu bez niepotrzebnego naruszania pozostałej konfiguracji PowerShella.