TIP#3307: Co je pipx a proč se hodí pro Pythonové nástroje spouštěné z Terminálu?

Pokud máte Pythonový skript nebo nástroj, který chcete spouštět odkudkoliv z Terminálu, můžete si ručně vytvořit venv, napsat spouštěcí skript a přidat alias nebo symlink. Funguje to, ale pipx umí velkou část této práce udělat automaticky.

pipx je určený hlavně pro Pythonové programy, které mají fungovat jako běžné příkazy v Terminálu. Každému vytvoří vlastní izolované Pythonové prostředí a jeho příkaz zpřístupní přes PATH.

pip, venv a pipx bez zbytečné vědy

pip je instalátor Pythonových balíčků.

venv vytvoří oddělené Pythonové prostředí. Program tak může mít vlastní Python a vlastní sadu potřebných balíčků, aniž by se míchaly s jinými programy.

Zjednodušeně:

muj-program
└── .venv
    ├── Python
    ├── balíček A
    ├── balíček B
    └── ...

Do tohoto prostředí se potřebné balíčky instalují pomocí pip.

Program pak můžete spustit například takto:

source .venv/bin/activate
python muj-program.py

Pokud ho ale chcete spouštět odkudkoliv, musíte si to zařídit navíc. Třeba vytvořit spouštěcí skript:

#!/bin/bash

DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
exec "$DIR/.venv/bin/python" "$DIR/muj-program.py" "$@"

a následně alias:

alias muj-program=~/muj-program/run

Potom už lze odkudkoliv napsat:

muj-program

pipx automatizuje právě velkou část tohoto řešení.

Pro každý nainstalovaný program vytvoří vlastní venv, nainstaluje do něj potřebné balíčky a jeho příkaz vystaví do adresáře dostupného přes PATH. Stejný způsob použití doporučuje i Python Packaging User Guide.

Nejdůležitější je tedy:

pipx není náhrada za venv. pipx vytváří a spravuje venv za vás a navíc zpřístupní program jako běžný příkaz.

Kdy má pipx smysl

Typický případ je Pythonový nástroj, který chcete používat stejně jako kterýkoliv jiný příkaz:

muj-program soubor.txt

Nechcete pokaždé:

cd ~/muj-program
source .venv/bin/activate
python muj-program.py soubor.txt

a nechcete ani pro každý podobný program ručně vytvářet vlastní run, aliasy a další pomocné věci.

V takovém případě je pipx velmi dobrá volba.

Pokud ale máte venv uvnitř Pythonového projektu kvůli jeho vývoji a závislostem, není důvod ho automaticky převádět na pipx. pipx je zaměřený především na samostatně spouštěné Pythonové aplikace, ne na správu prostředí libovolného projektu.

Jak dostat vlastní Pythonový program pod pipx

Nestačí mít pouze:

muj-program.py

Pipx instaluje Pythonové projekty, takže projekt musí být připravený jako instalovatelná aplikace.

Běžně k tomu slouží pyproject.toml. V něm lze také určit příkaz, kterým se má program spouštět:

[project.scripts]
muj-program = "muj_program:main"

To znamená: při zadání:

muj-program

se má spustit funkce main() z Pythonového modulu muj_program.

Podrobnosti k tomuto mechanismu najdete v Python Packaging User Guide.

Lokální projekt potom může pipx nainstalovat například:

pipx install ~/muj-program

Pokud jeho zdrojový kód stále upravujete, hodí se editable instalace:

pipx install -e ~/muj-program

Volbu --editable podporuje přímo aktuální příkaz pipx install.

Zdrojový kód zůstává na původním místě, ale pipx se stará o vlastní venv a zpřístupnění příkazu.

Co když už má program vlastní venv?

Existující venv pipx nepřevezme.

Máte-li:

muj-program/
├── .venv/
├── muj-program.py
└── ...

a rozhodnete se přejít na pipx, pipx vytvoří nové vlastní prostředí.

Po úspěšné instalaci a otestování programu přes pipx už starý .venv ani případný vlastní spouštěcí skript nemusí být potřeba.

To je důležité hlavně při převodu existujících nástrojů: nemažte původní prostředí dřív, než ověříte, že varianta přes pipx skutečně funguje.

Jak pipx nainstalovat

Na macOS je jednoduchá instalace přes Homebrew:

brew install pipx
pipx ensurepath

pipx ensurepath se postará o přidání adresáře s příkazy pipx do PATH. Po změně může být potřeba otevřít nový Terminál.

Aktuální postupy pro macOS, Linux i Windows jsou v oficiální dokumentaci instalace pipx.

Jak nainstalovat hotový nástroj

U programu dostupného jako Pythonový balíček může instalace vypadat jednoduše:

pipx install nazev-programu

Pipx:

vytvoří samostatný venv
        ↓
nainstaluje program a jeho závislosti
        ↓
zpřístupní jeho příkaz přes PATH

Program pak používáte bez ruční aktivace jeho venv.

Jak zjistit, co už pipx spravuje

Základní příkaz je:

pipx list

Ukáže nainstalované aplikace a příkazy, které zpřístupňují.

Kratší přehled:

pipx list --short

A pokud chcete vidět používané adresáře a další nastavení:

pipx environment

Aktuální dokumentace správy nainstalovaných aplikací je v Manage installed apps.

Pokud chcete zjistit, co se po zadání konkrétního příkazu skutečně spustí, hodí se také which nebo shellový type. Více najdete v Jak v Linuxu zjistit kde se nachází a odkud se spustí konkrétní příkaz? Použijte which.

Má tedy smysl převádět všechno na pipx?

Ne.

Pokud už máte jeden vlastní Pythonový nástroj s .venv, spouštěcím skriptem a aliasem a celé řešení spolehlivě funguje, není nutné ho předělávat jen proto, že existuje pipx.

Čím více podobných Pythonových utilit ale používáte, tím větší smysl pipx dává. Místo opakovaného vytváření:

.venv
+ init
+ run
+ alias nebo symlink

máte jeden standardní způsob instalace a jeden příkaz:

pipx list

kterým zjistíte, co tímto způsobem spravujete.

A hlavně: když někdo doporučí pipx, není za tím žádná další záhadná vrstva Pythonu. Uvnitř jsou pořád venvy. pipx pouze automatizuje jejich vytváření a zpřístupnění nainstalovaných programů jako běžných příkazů.