Co je Composer a jak ho nainstalovat správně

Composer je nástroj pro správu závislostí v PHP projektech. Automaticky stahuje, instaluje a aktualizuje knihovny (balíčky), které vaše aplikace potřebuje ke svému běhu, a kontroluje jejich vzájemnou kompatibilitu.

Pokud provozujete moderní PHP aplikaci — ať už jde o Laravel, Symfony, nebo i řadu WordPress projektů s pokročilejšími pluginy — je velmi pravděpodobné, že Composer budete potřebovat. Bez něj byste museli každou knihovnu stahovat, kopírovat a aktualizovat ručně, což je nejen zdlouhavé, ale i náchylné k chybám.

V tomto návodu vás provedeme instalací Composeru na VPS. Ukážeme dvě metody — instalaci přes oficiální instalátor (doporučujeme) a alternativní instalaci ze systémového repozitáře. Na konci článku najdete i návod na aktualizaci a řešení nejčastějších problémů.

Na serverech Váš Hosting s VPS Centrem je PHP i všechny potřebné moduly pro Composer předinstalované — můžete rovnou začít. Na čistém Ubuntu budete muset PHP CLI nejprve doinstalovat a na CentOS může chybět modul php-xml (obojí řešíme v Kroku 1). Návod pokrývá Debian (primární distribuce), Ubuntu i CentOS — u kroků, kde se příkazy liší, uvádíme varianty pro všechny tři distribuce.

Rychlý přehled pro pokročilé

Tato část slouží pouze pro ověření pro velmi zkušené uživatele, kteří si chtějí pouze ověřit postup a nepotřebují číst celý článek. Pro všechny ostatní doporučujeme pokračovat další sekcí.

1. Připojte se k serveru přes SSH jako root.
2. Stáhněte oficiální instalátor a ověřte jeho integritu (SHA-384 checksum).
3. Nainstalujte Composer globálně do /usr/local/bin/composer.
4. Smažte dočasné instalační soubory.
5. Ověřte instalaci příkazem composer --version a composer diagnose.
6. Alternativa: apt install composer (Debian/Ubuntu) nebo dnf install composer (CentOS) — verze z repozitáře bývá starší.

Co je dobré vědět předem

Časový odhad: Celá instalace zabere přibližně 5–10 minut.

Co budete potřebovat

Před instalací si připravte:

• SSH přístup k vašemu serveru. Pokud s SSH teprve začínáte, doporučujeme nejprve náš kompletní průvodce SSH, případně návod Jak se připojit na SSH pomocí WinSCP.
• Root přístup — na serverech Váš Hosting pracujete jako root, takže příkazy v tomto návodu zadáváte bez sudo.
• Distribuce — příkazy uvádíme primárně pro Debian Trixie. Tam, kde se liší, najdete varianty i pro Ubuntu a CentOS.

Kterou metodu instalace zvolit?

Composer můžete nainstalovat dvěma způsoby. Pokud si nejste jistí, zvolte oficiální instalátor — je to doporučená metoda.

	Oficiální instalátor (doporučeno)	Systémový repozitář (apt)
Verze	Vždy nejnovější	Závisí na repozitáři distribuce — bývá starší
Aktualizace	Příkazem composer self-update	Příkazem apt upgrade (Debian/Ubuntu)
Vhodné pro	Nové projekty, moderní frameworky (Laravel, Symfony), pokud potřebujete nejnovější funkce	Starší projekty bez speciálních požadavků na verzi
Složitost	O něco více kroků, ale identická na všech distribucích	Jeden příkaz (Debian/Ubuntu)
CentOS	✅ Funguje	❌ Composer není v repozitářích CentOS — použijte oficiální instalátor

Metoda 1: Instalace přes oficiální instalátor (doporučeno)

Krok 1: Ověřte dostupnost PHP a potřebných modulů

Po přihlášení k serveru přes SSH nejprve ověřte, že je PHP nainstalované a že máte k dispozici potřebné moduly. Zadejte následující příkaz:

php -v

Pokud je PHP správně nainstalované, uvidíte ve výstupu číslo verze, například:

PHP 8.x.x (cli) ...

apt update
apt install php-cli php-curl php-mbstring php-xml php-zip

Terminál se vás zeptá po zadání příkazů zda doopravdy chcete vše vypsané v řádku apt install nainstalovat, stačí potvrdit klávesou y.

Po dokončení ověřte instalaci znovu příkazem php -v. Pokud vidíte číslo verze, můžete pokračovat dalším krokem.

dnf install php-xml

Pokud se v pořádku php-xml nainstalovalo tak to uvidíte ve výpisu instalace.

Pro Composer jsou potřeba i jiné PHP moduly. Na serverech s Debianem jsou všechny předinstalované. Pokud chcete ověřit jejich přítomnost, spusťte:

php -m | grep -iE "curl|mbstring|xml|zip"

Ve výstupu by se měly objevit moduly curl, mbstring, xml (nebo xmlreader, xmlwriter) a zip.

Pokud některý z nich i přesto chybí, doinstalujte ho — příkaz se liší podle distribuce a podle toho co ve výpisu chybí:

Debian / Ubuntu:

apt install php-curl php-mbstring php-xml php-zip

CentOS:

dnf install php-curl php-mbstring php-xml php-zip

Na starších verzích CentOS, kde není k dispozici dnf, použijte místo něj yum (syntaxe příkazu je stejná).

Krok 2: Stáhněte instalátor a kontrolní podpis

Následující dva příkazy stáhnou oficiální instalační skript Composeru a jeho kontrolní podpis (checksum), který slouží k ověření, že soubor nebyl při stahování pozměněn:

php -r "copy('https://composer.github.io/installer.sig', 'expected.sig');"
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"

První příkaz stáhne kontrolní podpis a uloží ho do souboru expected.sig. Druhý příkaz stáhne samotný instalační skript a uloží ho jako composer-setup.php.

Pokud vše proběhne v pořádku, zobrazí se nový prázdný řádek bez chybové hlášky.

Krok 3: Ověřte integritu staženého souboru

Tento krok je nejdůležitější z hlediska bezpečnosti. Příkaz spočítá otisk (hash) staženého instalátoru a porovná ho s oficiálním podpisem:

php -r "if (hash_file('sha384', 'composer-setup.php') === trim(file_get_contents('expected.sig'))) { echo 'OK'; } else { echo 'BAD'; unlink('composer-setup.php'); exit(1); } echo PHP_EOL;"

Co příkaz dělá: Vypočítá SHA-384 hash souboru composer-setup.php, porovná ho s hodnotou v expected.sig. Pokud se shodují, vypíše OK. Pokud ne, vypíše BAD, smaže instalátor a ukončí se — v takovém případě zkuste soubory stáhnout znovu.

Pokud vše proběhlo správně, uvidíte ve výstupu:

OK

Krok 4: Nainstalujte Composer do systému

Následující příkaz spustí instalátor a nainstaluje Composer jako globálně dostupný příkaz:

php composer-setup.php --install-dir=/usr/local/bin --filename=composer

Co příkaz dělá: Spustí instalační skript a vytvoří spustitelný soubor composer v adresáři /usr/local/bin. Díky tomu bude Composer dostupný z jakéhokoli adresáře na serveru — stačí zadat příkaz composer.

Po úspěšné instalaci uvidíte výstup podobný tomuto:

All settings correct for using Composer
Composer (version X.X.X) successfully installed to: /usr/local/bin/composer

Krok 5: Ukliďte dočasné soubory

Po úspěšné instalaci smažte instalační skript a kontrolní podpis — na serveru už nejsou potřeba:

rm composer-setup.php expected.sig

SSH vás poté vyzve na potvrzení a to stačí zadat y (jako yes) a soubory se smažou. Vypadá to takto

stačí potvrdit písmenem y jako yes a jak instalační skript tak kontrolní podpis se smaže.

Krok 6: Ověřte instalaci

Nakonec ověřte, že Composer funguje správně:

composer --version

Příkaz by měl vypsat verzi Composeru:

Pro podrobnější kontrolu prostředí spusťte diagnostiku:

composer diagnose

Tento příkaz zkontroluje verzi PHP, SSL certifikáty, připojení k repozitáři Packagist, oprávnění a celkovou konfiguraci. Pokud je vše v pořádku, neuvidíte žádné chybové hlášky označené jako FAIL.

Metoda 2: Instalace přes systémový repozitář

Tento způsob je nejjednodušší — stačí jeden příkaz. Verze z repozitáře distribuce však bývá starší než ta z oficiálního instalátoru. Pro většinu běžných projektů je ale plně dostačující.

Krok 1: Aktualizujte seznam balíčků

Před instalací jakéhokoli balíčku je dobré aktualizovat seznam dostupných balíčků.

Debian / Ubuntu:

apt update

Na konci výstupu byste měli vidět potvrzení, že je vše aktualizované.

Krok 2: Nainstalujte Composer

Debian / Ubuntu:

apt install composer

Příkaz stáhne balíček composer z repozitáře distribuce, automaticky doinstaluje všechny potřebné závislosti a nainstaluje Composer do systémové cesty (typicky /usr/bin/composer).

Během instalace se systém může zeptat na potvrzení. Zadejte y a potvrďte klávesou Enter.

Krok 3: Ověřte instalaci

Po dokončení ověřte, že Composer funguje:

composer --version

Výstup zobrazí verzi Composeru. Pokud vidíte číslo verze a datum vydání, instalace proběhla úspěšně.

Volitelně můžete ověřit, odkud se Composer spouští:

which composer

Příkaz by měl vrátit cestu /usr/bin/composer (u instalace z repozitáře) nebo /usr/local/bin/composer (u instalace přes oficiální instalátor). Tento konkrétní postup byl pro repozitář proto naše cesta je v pořádku.

Composer a uživatel root

Po nainstalování Composeru se můžete pustit do práci s projekty. Při spuštění těchto příkazů jako root se může zobrazit varování:

Do not run Composer as root/super user! See https://getcomposer.org/root for details

Varování se zobrazuje proto, že balíčky mohou při instalaci spouštět vlastní skripty a vytvářet soubory. Pokud to probíhá pod rootem, výsledné soubory budou vlastněné rootem a webserver (Apache nebo Nginx) je nemusí správně přečíst.

Každá doména má na serveru vlastního systémového uživatele. Jeho jméno odpovídá názvu domény, kde se tečka nahrazuje pomlčkou — například pro doménu saldova.cz je to uživatel saldova-cz. Uživatele domény najdete také na SSH příkazem:

ls -la /www/hosting/DOMENA/www/

Třetí sloupec ve výpisu je jméno uživatele domény.

Uživatel domény je servisní účet bez přihlašovacího shellu — standardní příkaz su - nefunguje. Pro přepnutí je nutné zadat shell explicitně:

su -s /bin/bash UZIVATEL_DOMENY

Kde UZIVATEL_DOMENY je uživatel vaší domény (např. saldova-cz).

Jak používat Composer v projektu

Po úspěšné instalaci Composeru budete nejčastěji používat tyto příkazy. Spouštějte je vždy v adresáři vašeho projektu — například /www/hosting/DOMENA/www/ po přepnutí na uživatele domény.

Nejprve přejděte do adresáře vašeho webu:

cd /www/hosting/DOMENA/www/

Kde DOMENA je název vaší domény (například example.cz).

Práce s composer.json

Soubor composer.json je „seznam závislostí“ vašeho projektu — říká Composeru, které knihovny (balíčky) projekt potřebuje a v jakých verzích. Bez tohoto souboru Composer neví, co má stáhnout.

V praxi se setkáte se dvěma situacemi:

A) Projekt už composer.json má — to je nejčastější případ. Pokud jste nasadili existující PHP aplikaci (Laravel, Symfony, vlastní projekt), WordPress téma s Composer závislostmi, nebo klonovali repozitář z Gitu, soubor composer.json je už součástí projektu. Najdete ho v kořenovém adresáři webu:

ls /www/hosting/DOMENA/www/composer.json

Pokud soubor existuje, stačí spustit instalaci závislostí (viz níže).

B) Začínáte nový projekt od nuly — v tom případě composer.json vytvoříte příkazem:

composer init

Composer se vás postupně zeptá na název projektu, popis, autora a případné závislosti. Na většinu otázek můžete potvrdit výchozí hodnotu klávesou Enter. Po dokončení se v aktuálním adresáři vytvoří soubor composer.json. Podrobný popis jednotlivých položek najdete v oficiální dokumentaci Composeru.

Jak najít správný balíček

Balíčky pro Composer se publikují na packagist.org — je to centrální repozitář, ze kterého Composer standardně stahuje. Pokud potřebujete konkrétní knihovnu, najdete ji tam:

1. Otevřete packagist.org v prohlížeči.
2. Do vyhledávacího pole zadejte název knihovny nebo funkci, kterou hledáte (například „pdf generator“, „image resize“ nebo „mailer“).
3. Ve výsledcích uvidíte název balíčku ve formátu autor/nazev (například monolog/monolog nebo phpmailer/phpmailer), počet instalací a datum poslední aktualizace.
4. Tento název ve formátu autor/nazev pak použijete v příkazu composer require.

Nejčastější příkazy

Instalace závislostí — stáhne všechny knihovny definované v composer.json. Používá se po nasazení projektu na server nebo po klonování z Gitu:

composer install

Composer přečte composer.json, stáhne všechny potřebné knihovny do adresáře vendor/ a vygeneruje soubor composer.lock (přesný záznam nainstalovaných verzí).

Přidání nového balíčku — stáhne konkrétní knihovnu, přidá ji do composer.json a aktualizuje composer.lock:

composer require autor/nazev

Například pro přidání knihovny PHPMailer:

composer require phpmailer/phpmailer

Composer stáhne balíček do vendor/, automaticky doplní záznam do composer.json a aktualizuje composer.lock.

Aktualizace závislostí — aktualizuje všechny knihovny na nejnovější kompatibilní verze podle pravidel v composer.json:

composer update

Soubory, které Composer vytváří

Po prvním spuštění Composeru v projektu najdete v adresáři tyto nové soubory a adresáře:

Soubor / adresář	Co to je	Patří do Gitu?
composer.json	Seznam závislostí a jejich verzí	✅ Ano
composer.lock	Přesný záznam nainstalovaných verzí — zajišťuje, že na všech serverech budou identické verze	✅ Ano
vendor/	Adresář se staženými knihovnami	❌ Ne — je velký a generuje se příkazem composer install

Jak aktualizovat Composer

Jak zjistit, kterou metodou jste Composer nainstalovali

Pokud si nepamatujete, jakou metodou jste Composer nainstalovali, spusťte:

which composer

Výstup /usr/local/bin/composer znamená instalaci přes oficiální instalátor. Výstup /usr/bin/composer znamená instalaci z repozitáře (Debian/Ubuntu). Na CentOS je k dispozici pouze oficiální instalátor, takže cesta bude vždy /usr/local/bin/composer.

Pokud jste stále přihlášení jako uživatel domény tak je zapotřebí se odhlásit jinak vám aktualizace nebude fungovat. Z uživatele domény můžete vystoupit pomocí příkazu

exit

Aktualizace Composeru nainstalovaného přes oficiální instalátor

Spusťte příkaz:

composer self-update

Composer se aktualizuje na nejnovější stabilní verzi. Tento příkaz funguje pouze u instalace přes oficiální instalátor.

Aktualizace Composeru nainstalovaného z repozitáře (Debian/Ubuntu)

U instalace z repozitáře se Composer aktualizuje společně se systémovými balíčky:

apt update
apt upgrade composer

Nová verze Composeru se v repozitáři objeví až ve chvíli, kdy ji správci distribuce zařadí — proto může být k dispozici se zpožděním oproti oficiálnímu vydání.

Pokud jste Composer nainstalovali z repozitáře a potřebujete nejnovější verzi, můžete přejít na oficiální instalátor. Nejprve odstraňte repozitářovou verzi příkazem apt remove composer a poté postupujte podle Metody 1 výše.

Nejčastější problémy

„php: command not found“ (Ubuntu)

Symptom: Po zadání php -v nebo jakéhokoli příkazu s php se zobrazí:

-bash: php: command not found

Příčina: Na čistém Ubuntu není PHP CLI ve výchozím stavu nainstalované. Na serverech Váš Hosting s VPS Centrem a na Debianu je PHP předinstalované — tento problém se týká specificky Ubuntu.

Řešení: Nainstalujte PHP CLI spolu s potřebnými moduly:

apt update
apt install php-cli php-curl php-mbstring php-xml php-zip

Po dokončení ověřte příkazem php -v, že se zobrazí číslo verze.

Chybějící modul php-xml na CentOS

Symptom: Při ověření modulů příkazem php -m | grep -iE "xml" se zobrazí pouze libxml, ale nikoli xml, xmlreader nebo xmlwriter. Composer nebo PHP aplikace hlásí chybějící XML rozšíření.

Příčina: Na CentOS je předinstalovaná systémová knihovna libxml, ale PHP modul php-xml (který poskytuje xml, xmlreader, xmlwriter a xsl) ve výchozím stavu chybí.

Řešení: Doinstalujte modul:

dnf install php-xml

„composer: command not found“

Symptom: Po zadání composer se zobrazí hláška:

bash: composer: command not found

Příčina: Composer není v systémové cestě (PATH), nebo instalace neproběhla správně.

Řešení: Ověřte, zda soubor existuje:

ls -la /usr/local/bin/composer

Pokud soubor neexistuje, zopakujte instalaci. Pokud existuje, ale nemá nastavená práva ke spuštění, přidejte je:

chmod +x /usr/local/bin/composer

„No such file or directory“ po přeinstalaci Composeru

Symptom: Po odinstalování a opětovné instalaci Composeru jinou metodou (například z oficiálního instalátoru na repozitář) se zobrazí:

-bash: /usr/local/bin/composer: No such file or directory

Příčina: Bash si v aktuální relaci pamatuje cestu k příkazu z předchozí instalace (tzv. hash cache). Stará cesta (/usr/local/bin/composer) už neexistuje a nová (/usr/bin/composer) ještě není v cache.

Řešení: Vymažte cache cest příkazem:

hash -r

Poté spusťte composer --version znovu — bash najde Composer na správné cestě.

„Do not run Composer as root/super user“

Symptom: Při spuštění příkazu jako composer install nebo composer update se zobrazí varování o spuštění pod rootem.

Příčina: Composer doporučuje pracovat s projekty pod běžným uživatelem, nikoli jako root.

Řešení: Pro instalaci samotného Composeru je root v pořádku. Pro práci s projekty se přepněte na uživatele webu (viz sekce „Composer a uživatel root“ výše). Varování můžete potvrdit zadáním yes, pokud víte, co děláte.

„Your lock file does not contain a compatible set of packages“

Symptom: Po spuštění composer install se zobrazí chybová hláška o nekompatibilním lock souboru.

Příčina: Soubor composer.lock byl vytvořen s jinou verzí PHP nebo jinými závislostmi, než jaké jsou na serveru.

Řešení: Spusťte aktualizaci závislostí, která přegeneruje lock soubor:

composer update

„Could not find a version of package matching your php version“

Symptom: Při instalaci balíčku Composer hlásí, že nemůže najít kompatibilní verzi.

Příčina: Balíček vyžaduje novější (nebo jinou) verzi PHP, než která je nastavená pro danou doménu.

Řešení: Ověřte verzi PHP v terminálu:

php -v

Verzi PHP pro konkrétní doménu můžete změnit ve VPS Centru — vyberte doménu a v přehledu domény najdete nastavení verze PHP. Podrobnosti najdete v návodu Nastavení verze PHP pro subdomény.

Instalace selhává na timeout nebo síťovou chybu

Symptom: Při stahování balíčků se Composer zasekne nebo zobrazí chybu typu „The connection timed out“ nebo „Failed to download“.

Příčina: Dočasný problém s připojením k repozitáři Packagist nebo s DNS.

Řešení: Zkuste spustit příkaz znovu. Pokud problém přetrvává, spusťte diagnostiku:

composer diagnose

Tato diagnostika odhalí, zda jde o problém s DNS, SSL certifikáty nebo připojením k repozitáři.