Błąd ładowania modułu w PowerShell

Błąd ładowania modułu w PowerShell oznacza, że wskazany moduł nie jest zainstalowany w żadnej ze ścieżek $env:PSModulePath — rozwiązuje to instalacja modułu poleceniem `Install-Module` z odpowiedniego repozytorium.

Czym jest błąd ładowania modułu w PowerShell

Błąd ładowania modułu w PowerShell pojawia się wtedy, gdy środowisko nie potrafi odnaleźć albo uruchomić pakietu zawierającego potrzebne polecenia, funkcje, klasy lub dostawców. Moduł jest zbiorem plików rozszerzających możliwości powłoki, dlatego jego brak może zatrzymać skrypt już na etapie przygotowania środowiska. Komunikat często zawiera nazwę poszukiwanego modułu oraz informację, że nie znaleziono go w lokalizacjach przeszukiwanych przez PowerShell.

Nie zawsze oznacza to, że modułu nie ma na komputerze. Przyczyną może być również nieprawidłowa wartość zmiennej $env:PSModulePath, instalacja w profilu innego użytkownika, użycie niewłaściwej wersji PowerShell albo ograniczenie wynikające z polityki wykonywania skryptów. Znaczenie ma także sposób uruchomienia powłoki: moduł dostępny w sesji 64-bitowej może nie być widoczny w środowisku 32-bitowym, a element zainstalowany tylko dla bieżącego użytkownika może nie być dostępny podczas pracy z innym kontem.

Podczas analizy należy rozróżnić samo odnalezienie modułu od jego poprawnego załadowania. Polecenie Get-Module -ListAvailable pozwala sprawdzić, czy PowerShell widzi moduł w znanych lokalizacjach. Z kolei Import-Module sprawdza, czy jego pliki mogą zostać rzeczywiście wczytane. Jeżeli moduł pochodzi z repozytorium, można go doinstalować po zweryfikowaniu nazwy i źródła, na przykład za pomocą Install-Module. W środowisku wymagającym podwyższonych uprawnień może być konieczne uruchomienie konsoli jako administrator albo wybranie instalacji wyłącznie dla bieżącego użytkownika.

Kontekst techniczny i porównanie sposobów rozwiązywania - Błąd ładowania modułu w PowerShell

PowerShell wyszukuje moduły według ustalonej kolejności katalogów zapisanych w $env:PSModulePath. Zmienna może obejmować lokalizacje systemowe oraz katalog profilu użytkownika. Jeżeli ścieżka została zmieniona ręcznie, nadpisana przez skrypt startowy lub nieprawidłowo odziedziczona przez proces, polecenia mogą przestać być rozpoznawane mimo obecności odpowiednich plików na dysku. W takiej sytuacji pomocne jest wyświetlenie bieżącej wartości zmiennej, porównanie jej z katalogami modułów i sprawdzenie, czy nazwa folderu odpowiada nazwie modułu.

Warto odróżnić trzy sytuacje. Pierwsza występuje, gdy moduł nie został zainstalowany. Wtedy należy sprawdzić dostępne repozytoria, poprawność nazwy oraz zgodność pakietu z używaną wersją PowerShell. Druga polega na tym, że moduł istnieje, lecz nie znajduje się w żadnej aktywnej ścieżce wyszukiwania. Rozwiązaniem bywa korekta PSModulePath albo przeniesienie instalacji do właściwego katalogu. Trzecia dotyczy konfliktu zależności: moduł jest odnajdywany, ale podczas importu zgłasza brak biblioteki, niezgodną wersję albo błąd w pliku manifestu.

Do diagnostyki można wykorzystać między innymi Get-Command, Get-Module, Import-Module -Verbose oraz Test-Path. Szczegółowy tryb komunikatów ułatwia ustalenie, czy problem wystąpił przy wyszukiwaniu, odczycie manifestu, ładowaniu pliku skryptowego czy rejestrowaniu poleceń. Samo ponowne wpisanie komendy instalacyjnej nie zawsze przynosi skutek, ponieważ przyczyną może być blokada pliku, brak dostępu do repozytorium, filtr bezpieczeństwa lub pozostałości po wcześniejszej, niepełnej instalacji.

Istotna jest również różnica między modułem skryptowym, binarnym i modułem opartym na pliku manifestu. Moduł skryptowy może zawierać pliki .psm1, natomiast moduł binarny korzysta z bibliotek ładowanych przez środowisko uruchomieniowe. Manifest .psd1 może wskazywać wymagane moduły, minimalną wersję PowerShell oraz zależności, więc błąd zgłoszony przy imporcie jednego pakietu może wynikać z braków w innym. Właściwa diagnoza powinna uwzględniać cały łańcuch zależności, a nie tylko nazwę widoczną w pierwszej linijce komunikatu.

Typowe problemy i błędy towarzyszące - Błąd ładowania modułu w PowerShell

Częstym powodem jest literówka w nazwie modułu albo pomylenie nazwy pakietu z nazwą polecenia. Nazwa używana w Import-Module nie zawsze odpowiada nazwie pojedynczego cmdletu. W razie wątpliwości można sprawdzić informacje z repozytorium i porównać nazwę modułu z jego zawartością. Pomocne bywa również użycie autouzupełniania oraz odczytanie pełnego komunikatu zamiast kopiowania wyłącznie jego skróconej części.

Problemy powstają także po zmianie wersji PowerShell, aktualizacji systemu albo odtworzeniu profilu użytkownika. Moduł mógł zostać zainstalowany w katalogu przypisanym do wcześniejszej wersji środowiska, podczas gdy aktualna sesja przeszukuje inne lokalizacje. Podobny efekt może wystąpić po uruchomieniu skryptu z harmonogramu zadań, zdalnej sesji lub programu korzystającego z innego konta. Każda z tych metod może mieć własne zmienne środowiskowe i inne uprawnienia.

Do błędu może doprowadzić niespójność między architekturą procesu a biblioteką modułu. Jeżeli komponent wymaga określonego środowiska uruchomieniowego, import w niepasującej sesji zakończy się komunikatem o braku zależności albo niemożności załadowania biblioteki. Nie należy wtedy usuwać przypadkowych plików z katalogów systemowych. Bezpieczniej jest ustalić, która wersja modułu została zainstalowana, jakie wymagania podano w dokumentacji oraz czy w systemie znajduje się wymagane środowisko pomocnicze.

Inna grupa przyczyn wiąże się z zabezpieczeniami. Pliki pobrane z internetu mogą otrzymać oznaczenie blokady, a polityka wykonywania skryptów może ograniczać możliwość ich uruchomienia. Zmiana ustawień bezpieczeństwa bez rozpoznania źródła problemu może obniżyć ochronę systemu i nie musi naprawić importu. Należy najpierw sprawdzić właściwości pliku, pochodzenie modułu, podpis cyfrowy, komunikaty audytowe oraz zakres obowiązywania ewentualnej polityki.

W praktyce spotyka się też uszkodzone cache repozytoriów, zerwane pobieranie, brak dostępu do źródła pakietów i niepełne aktualizacje. Jeżeli moduł działał wcześniej, a przestał po zmianie konfiguracji, warto przeanalizować historię aktualizacji i profile PowerShell. Jeżeli błąd występuje tylko w jednym skrypcie, należy przejrzeć sposób importu, wymagane wersje oraz kolejność ładowania zależności. Jeśli pojawia się w wielu niezależnych poleceniach, większe znaczenie może mieć konfiguracja środowiska, ścieżki systemowe albo stan instalacji.

W jakich sytuacjach warto umówić wizytę serwisową - Błąd ładowania modułu w PowerShell

Do serwisu warto zgłosić problem, gdy błąd powtarza się po sprawdzeniu nazwy modułu, ścieżek wyszukiwania i dostępności pakietu, a przyczyna nadal nie jest jasna. Szczególnie uzasadniona jest konsultacja, gdy PowerShell przestał rozpoznawać wiele niezależnych poleceń, instalacja modułu kończy się błędem, system zgłasza problemy z uprawnieniami albo import działa tylko w wybranym profilu użytkownika. W takich przypadkach potrzebne może być prześledzenie konfiguracji systemowej, profili powłoki, wpisów środowiskowych i zależności używanych przez konkretny skrypt.

Przed przekazaniem sprzętu można przygotować pełną treść komunikatu, nazwę modułu, wersję PowerShell, wynik $PSVersionTable oraz informację, czy problem występuje w nowej sesji. Przydatne są także wyniki Get-Module -ListAvailable i odczyt $env:PSModulePath, o ile nie zawierają danych poufnych. Takie informacje skracają drogę do ustalenia, czy wystarczy poprawa konfiguracji, ponowna instalacja pakietu, czy potrzebna jest szersza kontrola stanu systemu.

W warszawskim serwisie komputerowym można zlecić sprawdzenie laptopa wraz z analizą środowiska PowerShell; dostępna jest darmowa diagnoza LAPTOPA. Podczas oględzin można zweryfikować, czy problem wynika z samego modułu, ścieżek systemowych, konta użytkownika, ograniczeń bezpieczeństwa czy uszkodzeń konfiguracji. Po rozpoznaniu przyczyny łatwiej dobrać działanie, które przywróci wykonywanie potrzebnych poleceń bez nieuzasadnionego wyłączania zabezpieczeń i bez przypadkowego usuwania elementów systemu.

Jeżeli błąd pojawia się po każdej aktualizacji, dotyczy kilku kont albo wpływa na automatyzację pracy, warto potraktować go jako problem konfiguracji, a nie pojedynczej literówki. Uporządkowanie wersji modułów, ścieżek, zależności i profili może zapobiec ponownemu wystąpieniu komunikatu. W razie potrzeby można również ustalić, które elementy powinny być ładowane automatycznie, a które lepiej importować jawnie w skrypcie wraz z kontrolą wymaganej wersji.