Hvordan bruke PyInstaller for å lage Python-kjørbare filer

Python, kraftig og allsidig som den er, mangler noen få nøkkelegenskaper. For det første gir Python ingen naturlig mekanisme for å kompilere et Python-program til en frittstående kjørbar pakke.

For å være rettferdig krevde den originale brukssaken til Python aldri frittstående pakker. Python-programmer har stort sett blitt kjørt på plass på systemer der en kopi av Python-tolk bodde. Men den økende populariteten til Python har skapt større etterspørsel etter å kjøre Python-apper på systemer uten installert Python-kjøretid.

Flere tredjeparter har utviklet løsninger for distribusjon av frittstående Python-apper. Den mest populære løsningen på gjengen, og den mest modne, er PyInstaller. PyInstaller gjør ikke prosessen med å pakke en Python-app til å gå helt smertefri, men den går langt der.

I denne artikkelen vil vi utforske det grunnleggende om å bruke PyInstaller, inkludert hvordan PyInstaller fungerer, hvordan du bruker PyInstaller for å lage en frittstående Python-kjørbar, hvordan du finjusterer Python-kjørbare filer du oppretter, og hvordan du kan unngå noen av de vanlige fallgruvene med å bruke PyInstaller.

Opprette en PyInstaller-pakke

PyInstaller er en Python-pakke, installert med pip (pip install pyinstaller). PyInstaller kan installeres i din standard Python-installasjon, men det er best å lage et virtuelt miljø for prosjektet du vil pakke og installere PyInstaller der.

PyInstaller fungerer ved å lese Python-programmet ditt, analysere all import det lager og binde kopier av importen med programmet ditt. PyInstaller leser i programmet ditt fra inngangspunktet. For eksempel hvis programmets inngangspunkt er myapp.py, ville du løpt pyinstaller myapp.py for å utføre analysen. PyInstaller kan oppdage og automatisk pakke mange vanlige Python-pakker, som NumPy, men du må kanskje gi tips i noen tilfeller. (Mer om dette senere.)

Etter å ha analysert koden din og oppdaget alle bibliotekene og modulene den bruker, genererer PyInstaller deretter en "spec-fil." Et Python-skript med utvidelsen .spec, inneholder denne filen detaljer om hvordan Python-appen din må pakkes sammen. Første gang du kjører PyInstaller på appen din, vil PyInstaller generere en spesifikasjonsfil fra bunnen av og fylle den ut med noen fornuftige standarder. Ikke kast denne filen; det er nøkkelen til å raffinere en PyInstaller-distribusjon!

Til slutt forsøker PyInstaller å produsere en kjørbar fra appen, med alle dens avhengigheter. Når den er ferdig, heter det en undermappe dist (som standard, du kan angi et annet navn) vises i prosjektkatalogen. Dette inneholder igjen en katalog som er den medfølgende appen din - den har en .ekse filen som skal kjøres, sammen med alle biblioteker og andre nødvendige filer som kreves.

Alt du trenger å gjøre for å distribuere programmet, er å pakke opp denne katalogen som en .glidelås fil eller annen pakke. Pakken må vanligvis hentes ut i en katalog der brukeren har skrivetillatelser for å kunne kjøre.

Testing av en PyInstaller-pakke

Det er en god sjanse for at ditt første forsøk på å bruke PyInstaller til å pakke en app ikke vil lykkes.

For å kontrollere om PyInstaller-pakken din fungerer, naviger til katalogen som inneholder den medfølgende kjørbare filen og kjør .ekse filen der fra kommandolinjen. Hvis den ikke kjører, bør feilene du ser skrevet ut på kommandolinjen gi et hint om hva som er galt.

Den vanligste årsaken til at en PyInstaller-pakke mislykkes, er at PyInstaller ikke klarer å pakke sammen en nødvendig fil. Slike manglende filer faller inn i noen få kategorier:

Skjult eller manglende import: Noen ganger kan ikke PyInstaller oppdage import av en pakke eller et bibliotek, vanligvis fordi det importeres dynamisk. Pakken eller biblioteket må spesifiseres manuelt.
Manglende frittstående filer: Hvis programmet er avhengig av eksterne datafiler som må pakkes med programmet, har PyInstaller ingen måte å vite. Du må inkludere filene manuelt.
Manglende binærfiler: Her igjen, hvis programmet ditt er avhengig av en ekstern binær som en .DLL som PyInstaller ikke kan oppdage, må du inkludere den manuelt.

Den gode nyheten er at PyInstaller gir en enkel måte å håndtere de ovennevnte problemene på. De .spec fil opprettet av PyInstaller inkluderer felt vi kan fylle ut for å gi detaljene som PyInstaller savnet.

Åpne .spec filen i en tekstredigerer og se etter definisjonen av Analyse gjenstand. Flere av parameterne ble sendt til Analyse er tomme lister, men de kan redigeres for å spesifisere de manglende detaljene:

skjult import for skjult eller manglende import: Legg til denne listen en eller flere strenger med navnene på bibliotekene du vil inkludere i appen din. Hvis du ønsket å legge til pandaer og bokeh, for eksempel, vil du spesifisere det som['pandaer', 'bokeh']. Legg merke til at de aktuelle bibliotekene må installeres i samme forekomst av Python der du kjører PyInstaller.
datas for manglende frittstående filer: Legg til en eller flere spesifikasjoner for filer i prosjekttreet ditt som du vil inkludere i prosjektet. Hver fil må sendes som en tuple som indikerer den relative banen til filen i prosjektkatalogen og den relative banen i distribusjonskatalogen der du vil plassere filen. For eksempel hvis du hadde en fil ./modeller/mainmodel.dat som du ønsket å inkludere i appen din, og du vil plassere den i en matchende underkatalog i distribusjonskatalogen din, vil du bruke ('./models/mainmodel.dat','./models') som en oppføring i skjultimport liste. Merk at du kan bruke glob-stil jokertegn for å spesifisere mer enn én fil.
binærfiler for manglende frittstående binærfiler: Som med datas, du kan bruke binærfiler å sende en liste over tupler som spesifiserer plassering av binærfiler i prosjekttreet og deres destinasjoner i distribusjonskatalogen Igjen, du kan bruke glob-stil jokertegn.

Husk at noen av listene som sendes til Analyse kan genereres programmatisk tidligere i .spec fil. Tross alt, .spec filen er bare et Python-skript med et annet navn.

Etter at du har gjort endringer i .spec fil, kjør PyInstaller på nytt for å gjenoppbygge pakken. Fra nå av må du imidlertid passere den modifiserte .spec fil som parameter (f.eks. pyinstaller myapp.spec). Test den kjørbare filen som før. Hvis noe fremdeles er ødelagt, kan du redigere det på nytt .spec fil og gjenta prosessen til alt fungerer.

Til slutt, når du er fornøyd med at alt fungerer som forutsatt, vil du kanskje redigere.spec fil for å forhindre at den pakkede appen din presenterer et kommandolinjevindu når den startes. I EXE objektinnstillinger i .spec fil, settkonsoll = falsk. Å undertrykke konsollen er nyttig hvis appen din har en grafisk brukergrensesnitt og du ikke vil ha et falskt kommandolinjevindu som fører brukere på villspor. Selvfølgelig, ikke endre denne innstillingen hvis appen din krever en kommandolinje.

Raffinering av en PyInstaller-pakke

Når du har pakket appen din med PyInstaller og kjører riktig, er det neste du sannsynligvis vil gjøre, å slanke den litt. PyInstaller-pakker er ikke kjent for å være smarte.

Fordi Python er et dynamisk språk, er det vanskelig å forutsi akkurat hva som er nødvendig i løpet av et gitt program. Av den grunn, når PyInstaller oppdager en pakkeimport, inkluderer den alt i den pakken, uansett om den faktisk brukes på kjøretid av programmet ditt eller ikke.

Her er de gode nyhetene. PyInstaller inkluderer en mekanisme for selektivt å ekskludere hele pakker, eller individuelle navnerom innen pakker. La oss for eksempel si at programmet importerer pakken foo, som inkluderer foo.bar og foo.bip. Hvis du med sikkerhet vet at programmet bare bruker logikk i foo.bar, kan du trygt ekskludere foo.bip og spar litt plass.

For å gjøre dette bruker du ekskluderer parameter sendt til Analyse objekt i .spec fil. Du kan sende en liste med navn - moduler på toppnivå eller punkterte navneområder - for å ekskludere fra pakken din. For eksempel å ekskludere foo.bip, ville du bare spesifisere['foo.bip'].

En vanlig utelukkelse du kan gjøre er tkinter, Python-biblioteket for å lage enkle grafiske brukergrensesnitt på tvers av plattformer. Som standard,tkinter og alle støttefilene er fullpakket med et PyInstaller-prosjekt. Hvis du ikke bruker tkinter i prosjektet ditt, kan du ekskludere det ved å legge til 'tkinter' til ekskluderer liste. Utelater tkinter reduserer størrelsen på pakken med rundt 7 MB.

En annen vanlig utelukkelse er testsuiter. Hvis en pakke som programmet ditt importerer, har en testpakke, kan testpakken ende opp med å bli inkludert i PyInstaller-pakken. Med mindre du faktisk kjører testpakken i det distribuerte programmet ditt, kan du trygt ekskludere det.

Husk at pakker som er opprettet med unntak, bør testes grundig før de brukes. Hvis du ender med å ekskludere funksjonalitet som brukes i et fremtidig scenario du ikke forventet, vil appen din gå i stykker.

Tips fra PyInstaller

Bygg din PyInstaller-pakke på operativsystemet du planlegger å distribuere på. PyInstaller støtter ikke bygninger på tvers av plattformer. Hvis du trenger å distribuere din frittstående Python-app på MacOS, Linux og Windows-systemer, må du installere PyInstaller og bygge separate versjoner av appen på hvert av disse operativsystemene.
Bygg din PyInstaller-pakke mens du utvikler appen din. Så snart du vet at du vil distribuere prosjektet ditt med PyInstaller, bygg ditt .spec fil og begynn å raffinere PyInstaller-pakken parallelt med utviklingen av appen din. På denne måten kan du legge til ekskluderinger eller inneslutninger mens du går, og teste måten nye funksjoner blir distribuert med appen mens du skriver dem.
Ikke bruk PyInstaller--onefile modus. PyInstaller inkluderer en kommandolinjebryter, --onefile, som pakker hele appen din i en enkelt selvutpakkende kjørbar. Dette høres ut som en god idé - du trenger bare å levere en fil! - men det har noen fallgruver. Når du kjører appen, må den først pakke ut alle filene i den kjørbare filen til en midlertidig katalog. Hvis appen er stor (for eksempel 200 MB), kan utpakking bety en forsinkelse på flere sekunder. Bruk standard enkeltkatalogmodus i stedet, og bare pakk alt opp som en .glidelås fil.
Opprett et installasjonsprogram for PyInstaller-appen din. Hvis du vil bruke en annen måte å distribuere appen din enn en .zip-fil, bør du vurdere å bruke et installasjonsverktøy som det åpne kildekoden Nullsoft Scriptable Install System. Det gir veldig lite overhead til størrelsen på leveransen, og lar deg konfigurere mange aspekter av installasjonsprosessen, som å lage snarveier til den kjørbare filen.
Ikke forvent hastigheter. PyInstaller er enemballasje system, ikke etkompilatoreller enoptimizer. Kode pakket med PyInstaller kjører ikke raskere enn den ville kjørt på det originale systemet. Hvis du vil øke hastigheten på Python-koden, kan du bruke et C-akselerert bibliotek som passer for oppgaven, eller et prosjekt som Cython.