Установка PHP-Imagick на Debian 13, 12, 11: полное руководство

Если ваш сайт или веб-приложение работает с изображениями — создаёт миниатюры, конвертирует форматы, обрабатывает загрузку файлов или генерирует PDF-превью — то расширение PHP Imagick вам жизненно необходимо. Без него многие функции обработки изображений будут недоступны, а скрипты — выдавать ошибки.

В этом руководстве мы установим PHP-Imagick на Debian двумя способами: стандартным (из официальных репозиториев Debian) и продвинутым (из репозитория Sury, если вам нужна конкретная версия PHP). Я подробно разберу каждую команду и научу вас диагностировать и решать типичные проблемы.

Оглавление

Предварительные требования

Перед установкой убедитесь, что:

  • У вас установлен PHP (любой версии). Если нет — сначала установите PHP на Debian.
  • На сервере настроен веб-сервер (Apache или Nginx) с PHP-FPM или модулем libapache2-mod-php.

⚠️ ВАЖНО: Проверьте права sudo перед установкой

Если вы не уверены, есть ли у вашего пользователя права администратора, выполните в терминале:

sudo whoami

Что делает: sudo — выполняет команду от имени суперпользователя; whoami — показывает имя текущего пользователя.

✅ Ожидаемый вывод в терминале:

root

❌ Если выводит is not in the sudoers file — сначала пройдите наше руководство по настройке sudo.

Способ 1: Установка PHP-Imagick из официальных репозиториев Debian (рекомендуемый)

Этот способ подходит для большинства серверов. Вы получите расширение, совместимое с версией PHP, которая идёт в вашем релизе Debian по умолчанию.

Релиз DebianВерсия PHP по умолчаниюПакет расширения
Debian 13 (Trixie)PHP 8.4php-imagick (устанавливает
php8.4-imagick)
Debian 12 (Bookworm)PHP 8.2php-imagick (устанавливает
php8.2-imagick)
Debian 11 (Bullseye)PHP 7.4php-imagick

Шаг 1: Обновите список пакетов и систему

sudo apt update && sudo apt upgrade -y

Что делает:

  • sudo — права суперпользователя
  • apt update — обновляет список доступных пакетов из репозиториев
  • && — выполняет следующую команду только если предыдущая завершилась успешно
  • apt upgrade -y — обновляет все установленные пакеты до свежих версий, -y автоматически подтверждает обновление

Зачем: Это стандартная практика безопасности перед установкой нового ПО. Вы получаете актуальные версии пакетов и избегаете конфликтов зависимостей.

Шаг 2: Установите PHP-Imagick

sudo apt install php-imagick

Что делает: Устанавливает пакет php-imagick и все необходимые зависимости (библиотеки ImageMagick, дополнительные PHP-пакеты).

Ожидаемый вывод в терминале (пример для Debian 13):

The following NEW packages will be installed:
  php-common php-imagick php8.4-cli php8.4-common php8.4-imagick
  php8.4-opcache php8.4-phpdbg php8.4-readline
0 upgraded, 8 newly installed, 0 to remove and 0 not upgraded.

На Debian 12 вместо php8.4-* будут пакеты php8.2-*, на Debian 11 — php7.4-*.

Шаг 3: Проверьте, что расширение загружено для командной строки (CLI)

php -m | grep -x imagick

Что делает:

  • php -m — показывает список всех загруженных модулей PHP
  • | (вертикальная черта) — передаёт вывод первой команды на вход второй
  • grep -x imagick — ищет точное совпадение со словом imagick (флаг -x требует полного совпадения строки)

✅ Ожидаемый вывод в терминале:

imagick

Если вы видите imagick — расширение успешно загружено для PHP CLI.

Способ 2: Установка версии PHP-Imagick для конкретной ветки PHP (из репозитория Sury)

Этот способ нужен, если:

  • Вы используете PHP версии, отличной от той, что идёт в Debian по умолчанию (например, PHP 8.3 на Debian 12).
  • Вы уже подключили репозиторий Sury и установили из него специфическую версию PHP.

Шаг 1: Установите необходимые утилиты

sudo apt install ca-certificates curl

Что делает: Устанавливает пакеты сертификатов (ca-certificates) и утилиту curl для загрузки файлов по сети.

Зачем: Нам понадобится curl, чтобы скачать ключ репозитория, а сертификаты нужны для безопасного подключения по HTTPS.

Шаг 2: Скачайте и установите ключ репозитория Sury

curl -fsSLo /tmp/debsuryorg-archive-keyring.deb https://packages.sury.org/debsuryorg-archive-keyring.deb
sudo dpkg -i /tmp/debsuryorg-archive-keyring.deb

Что делает:

  • curl -fsSLo — загружает файл с указанного URL:
  • -f — возвращать ошибку при неудаче
  • -s — тихий режим (без прогресс-бара)
  • -S — показывать ошибки
  • -L — следовать перенаправлениям
  • -o — сохранить в файл
  • /tmp/debsuryorg-archive-keyring.deb — временный файл для сохранения
  • dpkg -i — устанавливает DEB-пакет с ключом репозитория

Зачем: Репозиторий Sury подписан цифровым ключом. Установка этого пакета добавляет ключ в систему, чтобы apt мог проверить подлинность пакетов из этого репозитория.

Шаг 3: Автоматически определите кодовое имя вашего Debian

CODENAME=$(. /etc/os-release && echo "$VERSION_CODENAME")
echo $CODENAME

Что делает:

  • . /etc/os-release — загружает переменные из файла /etc/os-release, где хранится информация о релизе
  • && — затем выполняет echo "$VERSION_CODENAME", выводя кодовое имя (trixie, bookworm или bullseye)
  • CODENAME=... — сохраняет это значение в переменную CODENAME
  • echo $CODENAME — проверяет, что определение прошло успешно

✅ Ожидаемый вывод (пример для Debian 13):

trixie

Зачем: Мы будем использовать эту переменную при создании файла репозитория, чтобы он автоматически подстроился под ваш релиз Debian.

Шаг 4: Создайте файл репозитория Sury в формате DEB822

printf '%s\n' \
"Types: deb" \
"URIs: https://packages.sury.org/php/" \
"Suites: ${CODENAME}" \
"Components: main" \
"Signed-By: /usr/share/keyrings/debsuryorg-archive-keyring.gpg" | sudo tee /etc/apt/sources.list.d/sury-php.sources > /dev/null

Что делает:

  • printf '%s\n' ... — выводит каждую строку в кавычках, добавляя перевод строки
  • \ (обратный слэш) — позволяет разбить длинную команду на несколько строк
  • | sudo tee /etc/apt/sources.list.d/sury-php.sources — передаёт вывод printf команде tee, которая записывает его в файл с правами root
  • > /dev/null — подавляет вывод tee на экран (чтобы не дублировать)

Зачем: Современный Debian использует файлы .sources в формате DEB822 вместо старых .list. Мы создаём такой файл вручную, чтобы избежать ошибок apt update.

Шаг 5: Проверьте содержимое созданного файла

cat /etc/apt/sources.list.d/sury-php.sources

Что делает: cat — выводит содержимое файла.

✅ Ожидаемый вывод (пример для Debian 13):

Types: deb
URIs: https://packages.sury.org/php/
Suites: trixie
Components: main
Signed-By: /usr/share/keyrings/debsuryorg-archive-keyring.gpg

Шаг 6: Обновите список пакетов и проверьте репозиторий

sudo apt update

Что делает: Обновляет списки пакетов из всех подключённых репозиториев, включая новый Sury.

Ожидаемый вывод (должны быть строки с packages.sury.org):

Get:1 https://packages.sury.org/php trixie InRelease
Get:2 https://packages.sury.org/php trixie/main amd64 Packages
...

Теперь проверим, видит ли apt пакет для нужной версии PHP (замените 8.4 на вашу версию):

apt-cache policy php8.4-imagick

Что делает: apt-cache policy — показывает информацию о доступных версиях пакета.

Зачем: Убедиться, что пакет есть в репозитории Sury и что apt может его установить.

Шаг 7: Установите версионный пакет PHP-Imagick

sudo apt install php8.4-imagick

Что делает: Устанавливает конкретную версию расширения (здесь php8.4-imagick).

⚠️ Важно: Замените 8.4 на вашу версию PHP: 8.3, 8.2, 8.1 или другую. Если не знаете свою версию, выполните:

php -v | head -n 1

Это покажет что-то вроде PHP 8.4.1 (cli). Значит, вам нужен пакет php8.4-imagick.

Шаг 8: Проверьте загрузку расширения

php -m | grep -x imagick

✅ Ожидаемый вывод: imagick

Сравнение методов установки PHP-Imagick

МетодКаналВерсии PHPОбновленияДля кого
Debian APTОфициальные
репозитории
Debian		PHP 8.4 (Deb 13),
8.2 (Deb 12),
7.4 (Deb 11)		Через
apt upgrade		Большинство
серверов,
использующих
стандартную PHP
Sury PHPРепозиторий SuryКонкретные версии:
8.4, 8.3, 8.2, 8.1
и старше		Через
apt upgrade		Серверы с
нестандартной
версией PHP или
устаревшие
релизы

Решение типичных проблем

8.1 Ошибка: Class ‘Imagick’ not found

Симптом: При запуске PHP-скрипта, который использует new Imagick(), появляется фатальная ошибка:

Fatal error: Class 'Imagick' not found in /var/www/html/script.php on line X

Причина: Расширение Imagick либо не установлено, либо загружено не для той версии PHP, которую использует ваш веб-сервер или скрипт.

Пошаговое решение:

Шаг 1: Проверьте, установлено ли расширение для CLI (командной строки):

php -m | grep imagick

Что делает: Показывает, загружено ли расширение в командной версии PHP.
Что ищем: Строку imagick.
Если её нет — расширение не установлено. Вернитесь к шагам установки.

Шаг 2: Узнайте, какой SAPI (интерфейс) использует ваш веб-сервер:

  • Apache с mod_php — нужно перезагрузить Apache
  • PHP-FPM — нужно перезагрузить соответствующий пул
# Проверяем, запущен ли PHP-FPM
systemctl list-units --type=service 'php*-fpm.service'

Что делает: Показывает все сервисы PHP-FPM в системе.

Шаг 3: Перезапустите нужный сервис:

Для Apache:

sudo systemctl restart apache2

Для PHP-FPM (замените 8.4 на вашу версию):

sudo systemctl restart php8.4-fpm

Шаг 4: Создайте простой PHP-файл для проверки в веб-доступе:

# Для Apache (стандартная директория Debian)
echo "<?php phpinfo(); ?>" | sudo tee /var/www/html/info.php

# Для Nginx (если вы используете стандартную настройку)
# echo "<?php phpinfo(); ?>" | sudo tee /usr/share/nginx/html/info.php

Что делает: Создаёт файл info.php в директории по умолчанию для вашего веб-сервера. Убедитесь, что вы раскомментировали и используете нужную строку для Apache или Nginx.

Шаг 5: Откройте в браузере http://ваш_сервер/info.php и найдите строку imagick. Если она есть — расширение загружено.

⚠️ Важно: После проверки удалите файл info.php:

sudo rm /var/www/html/info.php
# Для Nginx: sudo rm /usr/share/nginx/html/info.php

Оставлять такой файл на рабочем сервере опасно — он раскрывает конфиденциальную информацию.

8.2 Ошибка: Несовпадение версий PHP и пакета Imagick

Симптом: Расширение установлено, но не загружается. Команда php -m | grep imagick ничего не показывает.

Причина: Вы установили пакет php8.4-imagick, но ваша активная версия PHP — 8.2 (или наоборот).

Пошаговое решение:

Шаг 1: Определите активную версию PHP:

php -v | head -n 1

Пример вывода:

PHP 8.2.20 (cli)

Шаг 2: Посмотрите, какой пакет Imagick установлен:

dpkg -l 'php*-imagick' | grep '^ii'

Что делает: dpkg -l — список установленных пакетов, фильтр 'php*-imagick' — ищет пакеты с именем, начинающимся на php и заканчивающимся на -imagick, grep '^ii' — показывает только полностью установленные пакеты.

Что означают символы в начале строки:

  • ii — пакет установлен корректно
  • iU или iF — пакет не доустановлен (проблемы с зависимостями)

Пример вывода:

ii  php8.4-imagick  3.7.0-1  amd64  Provides a wrapper to the ImageMagick library

Шаг 3: Если версии не совпадают (в примере PHP 8.2, а пакет 8.4), удалите неверный пакет и установите правильный:

# Удаляем неверный пакет
sudo apt remove php8.4-imagick

# Устанавливаем нужный (для PHP 8.2)
sudo apt install php8.2-imagick

Шаг 4: Перезапустите веб-сервер или PHP-FPM (как описано в проблеме 8.1).

8.3 Ошибка: Пакет php-imagick не найден

Симптом: При попытке установить php-imagick появляется сообщение:

E: Unable to locate package php-imagick

Причина: Не подключены репозитории main, contrib и non-free, или не обновлён список пакетов.

Пошаговое решение:

Шаг 1: Проверьте, какие репозитории подключены:

cat /etc/apt/sources.list | grep -vE '^#|^$'

Что делает: Выводит содержимое файла /etc/apt/sources.list, исключая закомментированные строки (начинающиеся с #) и пустые строки.

Шаг 2: Если нет строк с main contrib non-free, добавьте их. Для Debian 13, 12, 11:

sudo sed -i 's/main/main contrib non-free/g' /etc/apt/sources.list

Что делает: sed -i — редактирует файл на месте; 's/main/main contrib non-free/g' — заменяет каждое слово main на main contrib non-free в каждой строке.

Зачем: Пакет php-imagick и его зависимости (ImageMagick) находятся в этих репозиториях.

Шаг 3: Обновите список пакетов:

sudo apt update

Шаг 4: Повторите установку:

sudo apt install php-imagick

8.4 Ошибка: Не удаётся подключить репозиторий Sury (404 Not Found)

Симптом: При выполнении sudo apt update появляются ошибки:

Err:1 https://packages.sury.org/php trixie InRelease
  404  Not Found

Причина: Вы указали неверное кодовое имя релиза в файле репозитория.

Пошаговое решение:

Шаг 1: Проверьте ваше кодовое имя Debian:

. /etc/os-release && echo "$VERSION_CODENAME"

Шаг 2: Удалите неверный файл репозитория:

sudo rm /etc/apt/sources.list.d/sury-php.sources

Шаг 3: Заново создайте файл, используя правильное кодовое имя (повторите шаги 3-6 из способа 2).

Шаг 4: Если ошибка остаётся — возможно, Sury не поддерживает ваш старый релиз. Проверьте список поддерживаемых версий на сайте Sury.

8.5 Ошибка: Нет прав на запись при обработке изображений

Симптом: Расширение Imagick установлено, но при попытке сохранить обработанное изображение возникает ошибка Permission denied.

Причина: Веб-сервер (пользователь www-data) не имеет прав на запись в директорию, куда вы пытаетесь сохранить изображения.

Пошаговое решение:

Шаг 1: Узнайте, от какого пользователя работает ваш веб-сервер:

Для Apache:

ps aux | grep apache | grep -v grep | head -n 1 | awk '{print $1}'

Для Nginx с PHP-FPM:

ps aux | grep php-fpm | grep -v grep | head -n 1 | awk '{print $1}'

Обычно это www-data.

Шаг 2: Проверьте права на целевую директорию:

ls -la /путь/к/директории/

Пример вывода:

drwxr-xr-x 2 root root 4096 May 15 10:00 uploads

В этом примере владелец — root, поэтому www-data не может туда записывать.

Шаг 3: Измените владельца или права:

Вариант A (рекомендуемый) — сделать владельцем www-data:

sudo chown -R www-data:www-data /путь/к/директории/

Вариант B — дать права на запись для группы (если директория должна остаться у root):

sudo chmod -R 775 /путь/к/директории/
sudo chgrp -R www-data /путь/к/директории/

Что означают права:

  • 775 — владелец: всё (7=rwx), группа: чтение и запись (7=rwx), остальные: только чтение и выполнение (5=rx)

Шаг 4: Проверьте, что теперь можно создать файл:

sudo -u www-data touch /путь/к/директории/test.txt && echo "OK" || echo "FAIL"

Чек-лист: что проверить после установки

После установки PHP-Imagick выполните эти проверки, чтобы убедиться, что всё работает корректно:

  • [ ] Расширение загружено в CLI: php -m | grep imagick → вывод imagick
  • [ ] Веб-сервер перезапущен: sudo systemctl restart apache2 или sudo systemctl restart php8.4-fpm
  • [ ] Расширение видно в phpinfo(): создали и удалили info.php с phpinfo(), нашли блок imagick
  • [ ] Нет конфликта версий: php -v и dpkg -l 'php*-imagick' показывают одинаковые версии
  • [ ] Можно создать миниатюру: выполните в терминале:
php -r '$image = new Imagick(); $image->newImage(100, 100, "red"); $image->writeImage("/tmp/test.png"); echo file_exists("/tmp/test.png") ? "OK" : "FAIL";'

✅ Ожидаемый вывод: OK

Обновление PHP-Imagick

Обновление зависит от того, откуда вы устанавливали расширение.

Для пакета из официальных репозиториев:

sudo apt update && sudo apt install --only-upgrade php-imagick

Для пакета из репозитория Sury:

sudo apt update && sudo apt install --only-upgrade php8.4-imagick

(замените 8.4 на вашу версию)

Что делает: --only-upgrade — обновляет пакет, только если он уже установлен, но не устанавливает его заново.

Удаление PHP-Imagick

Полное удаление пакета:

sudo apt remove php-imagick
sudo apt autoremove

Что делает: apt remove — удаляет пакет, оставляя конфиги; apt autoremove — удаляет пакеты, установленные как зависимости и больше не нужные.

⚠️ Внимание: При удалении php-imagick на чистой системе Debian 13 autoremove может также удалить php8.4-cli и другие базовые пакеты. Внимательно читайте список удаляемых пакетов перед подтверждением!

Для удаления версионного пакета:

sudo apt remove php8.4-imagick
sudo apt autoremove

Если вы хотите полностью отключить репозиторий Sury:

sudo rm /etc/apt/sources.list.d/sury-php.sources
sudo apt remove debsuryorg-archive-keyring
sudo apt update

Проверьте, что репозиторий удалён:

grep -R "packages.sury.org/php" /etc/apt/sources.list /etc/apt/sources.list.d 2>/dev/null

✅ Ожидаемый вывод: пустота (ни одной строки).

Часто задаваемые вопросы (FAQ)

Вопрос: Нужен ли мне репозиторий Sury для установки PHP-Imagick?
Ответ: Нет. Debian 13, 12 и 11 уже содержат php-imagick в стандартных репозиториях. Sury нужен только если вы используете нестандартную версию PHP (например, PHP 8.3 на Debian 12).

Вопрос: В чём разница между php-imagick и ImageMagick?
Ответ: php-imagick — это расширение PHP, которое позволяет PHP-скриптам использовать библиотеки ImageMagick. А ImageMagick — это набор самостоятельных консольных утилит (convert, identify, magick и др.). Они не взаимозаменяемы.

Вопрос: Какой пакет ставить: php-imagick или php8.4-imagick?
Ответ: Если вы устанавливаете из официальных репозиториев Debian — ставьте php-imagick. Если из Sury — ставьте версионный пакет, соответствующий вашей PHP (php8.4-imagick, php8.3-imagick и т.д.).

Вопрос: Почему после установки PHP всё равно говорит Class Imagick not found?
Ответ: Две самые частые причины: 1) Не совпадают версии PHP и пакета Imagick (проверьте через php -v и dpkg -l 'php*-imagick'). 2) Не перезапущен PHP-FPM или Apache (выполните sudo systemctl restart php8.4-fpm).

Заключение

Теперь PHP-Imagick установлен на вашем Debian и готов к обработке изображений: созданию миниатюр, конвертации форматов, работе с PDF и многому другому.

Что дальше?

Связанные записи