---
title: "PHP GD Extension Nasıl Etkinleştirilir? XAMPP, Linux ve Docker"
url: "https://cilginyazilim.com/blog/php-gd-extension-nasil-etkinlestirilir"
description: "PHP GD extension nasıl etkinleştirilir: XAMPP'te php.ini, Linux'ta paket, Docker'da derleme; WebP desteğini ve Composer ext-gd hatasını doğrulama."
published: "2026-11-22T10:00:00+03:00"
modified: "2026-11-22T10:00:05+03:00"
author: "Çılgın Yazılım"
category: "Geliştirici Araçları"
tags: ["php", "codeigniter", "docker", "linux", "composer", "geliştirme ortamı"]
site: "Çılgın Yazılım"
language: "tr"
---

# PHP GD Extension Nasıl Etkinleştirilir? XAMPP, Linux ve Docker

Eklentiyi açtınız, Apache'yi yeniden başlattınız, Composer hâlâ GD yok diyor. Böyle bir durumda ilk bakılacak yer eklenti değil, düzenlediğiniz php.ini dosyasıdır.

PHP GD extension, PHP'nin görsel oluşturma ve işleme eklentisidir: küçük resim üretmek, görseli WebP'ye çevirmek ya da PDF'e resim gömmek gibi işler ona dayanır. Windows ve XAMPP'te php.ini dosyasındaki `;extension=gd` satırını açıp Apache'yi yeniden başlatmak, Debian ve Ubuntu'da `php8.2-gd` gibi sürümlü paketi kurmak, Docker'da ise eklentiyi bağımlılıklarıyla derlemek yeterlidir. Oysa en çok zaman kaybettiren adım bunlar değil, **yanlış php.ini dosyasını düzenlemektir**.

Eklenti kapalıyken hata genellikle başka bir yerden gelir: Composer "ext-gd" der, dompdf gibi kütüphaneler "the PHP GD extension is required" diye durur.

![PHP GD eklentisinin yüklendiğini doğrulamak için kontrol sırası](https://cilginyazilim.com/uploads/blog/2026/09/php-gd-extension-nasil-etkinlestirilir-ozet.png)
*İlk soru eklentinin varlığı değil, hangi php.ini dosyasının okunduğudur.*

## Adım 1: PHP'nin hangi php.ini dosyasını okuduğunu bulun

Bir şeyi değiştirmeden önce, çalışan PHP'nin gerçekten hangi dosyayı okuduğunu öğrenin. Komut satırında bunu tek komut söyler:

```bash
php --ini
# Loaded Configuration File:         C:\xampp\php\php.ini
```

Dikkat: bu, komut satırındaki PHP'nin dosyasıdır; web sunucusu başka bir dosya okuyor olabilir.

XAMPP'te Apache, `httpd-xampp.conf` içindeki `PHPINIDir` satırıyla aynı klasörü gösterir, yani iki taraf aynı dosyayı paylaşır. Debian ve Ubuntu'da ise komut satırı, Apache modülü ve PHP-FPM için ayrı dosyalar vardır: `/etc/php/8.2/cli/php.ini`, `/etc/php/8.2/apache2/php.ini` ve `/etc/php/8.2/fpm/php.ini`. "Tarayıcıda çalışıyor, Composer'da çalışmıyor" durumunun arkasında çoğu zaman bu ayrım vardır.

## Adım 2: XAMPP ve Windows'ta eklentiyi açın

Windows'ta GD, PHP ile birlikte gelen `php_gd.dll` dosyasıdır; kurmanız gerekmez, yalnız açmanız gerekir. php.ini dosyasında satırı bulup başındaki noktalı virgülü kaldırın:

```ini
; Önce: kapalı
;extension=gd

; Sonra: açık (PHP 8.0 ve sonrası)
extension=gd
```

PHP 8.0'dan eski sürümlerde dosyanın adı `php_gd2.dll`, satır da `extension=gd2` idi. Eski bir rehberdeki satırı PHP 8'e kopyalarsanız eklenti yüklenmez ve PHP açılışta "Unable to load dynamic library" uyarısı verir; bu tür uyarıların diğer nedenleri için [PHP hata mesajları ve hızlı çözümleri](https://cilginyazilim.com/blog/php-hatalari-ve-hizli-cozumleri) yazısına bakabilirsiniz.

Kaydettikten sonra XAMPP Kontrol Paneli'nden Apache'yi durdurup yeniden başlatın. Komut satırındaki PHP ise dosyayı her çalıştırmada yeniden okur.

## Adım 3: Linux'ta paketi kurun

Linux dağıtımlarında GD ayrı bir paket olarak gelir. Paket adındaki sürüm, çalışan PHP'nin sürümüyle aynı olmalıdır:

```bash
php -v                                # ör. PHP 8.2.x
sudo apt install php8.2-gd            # Debian / Ubuntu
sudo systemctl restart php8.2-fpm     # Apache modülü kullanıyorsanız: apache2
ls /etc/php/8.2/*/conf.d/ | grep gd   # her ortamda 20-gd.ini görünmeli
# RHEL, Rocky, AlmaLinux: sudo dnf install php-gd
```

Debian ve Ubuntu paketi eklentiyi komut satırı dahil bütün PHP ortamlarında kendisi açar; son komut bunu doğrular. Sunucuda birden fazla PHP sürümü kuruluysa sürüm numarasız `php-gd` paketi varsayılan sürüme kurulur; siteniz başka bir sürümde çalışıyorsa hiçbir şey değişmez.

## Adım 4: Docker imajında derleyin

Resmî `php` Docker imajlarında GD kaynak koddan derlenir ve görsel biçimlerinin kütüphaneleri ayrıca kurulur. WebP desteği de istiyorsanız resmî örneğe `libwebp-dev` paketini ve `--with-webp` seçeneğini ekleyin:

```dockerfile
FROM php:8.2-fpm
RUN apt-get update && apt-get install -y \
        libfreetype-dev libjpeg62-turbo-dev libpng-dev libwebp-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg --with-webp \
    && docker-php-ext-install -j$(nproc) gd \
    && rm -rf /var/lib/apt/lists/*
```

Dikkat: bağımlılıkları kurmadan yalnız `docker-php-ext-install gd` yazarsanız eklenti ya hiç derlenmez ya da JPEG ve WebP desteği olmadan derlenir; bunu test adımında görürsünüz. Son satır apt paket listelerini aynı katmanda siler; imajı küçültmenin diğer yolları için [katman katman küçültme](https://cilginyazilim.com/blog/docker-imaji-kucultme-katman-katman) yazısına bakabilirsiniz.

## Composer ext-gd hatası: kontrolü susturmayın

Projeniz GD'ye bağlı bir paket kullanıyorsa ve komut satırındaki PHP'de eklenti yoksa Composer kurulumu durdurur. `composer.lock` dosyası varken çıktı şöyledir:

```bash
$ composer install
Installing dependencies from lock file (including require-dev)
Verifying lock file contents can be installed on current platform.
Your lock file does not contain a compatible set of packages. Please run composer update.

  Problem 1
    - Root composer.json requires PHP extension ext-gd * but it is missing from your system. Install or enable PHP's gd extension.
```

Lock dosyası yoksa ilk satır "Your requirements could not be resolved to an installable set of packages." olur; GD'yi bir bağımlılık istiyorsa satırda o paketin adı yazar. Mesajın önerdiği `composer update` sorunu çözmez, çünkü eksik olan paket değil eklentidir.

`--ignore-platform-req=ext-gd` seçeneği de kurulumu geçirir ama eklentiyi yüklemez; kod ilk görsel işleminde çalışma anında hata verir. Bu seçenek yalnız kurulumu GD'siz bir makinede yapıp kodu GD'li başka bir ortamda çalıştıracaksanız anlamlıdır. Doğru çözüm, Adım 1'de bulduğunuz dosyada eklentiyi açmaktır.

## Test etmek: eklenti gerçekten yüklendi mi?

Komut satırında iki kontrol yeter: eklenti listede mi ve beklediğiniz biçimleri destekliyor mu?

```bash
php -m | grep -i gd            # Windows: php -m | findstr /i gd
php -r "var_dump(extension_loaded('gd'), function_exists('gd_info') && (gd_info()['WebP Support'] ?? false));"
# GD ve WebP açıksa: bool(true) bool(true)
# GD yoksa:          bool(false) bool(false)
```

Web tarafı için geçici bir PHP dosyasına `var_dump(extension_loaded('gd'), php_ini_loaded_file());` yazıp tarayıcıda açın: ilk değer eklentinin yüklendiğini, ikincisi web tarafının hangi php.ini dosyasını okuduğunu gösterir. CodeIgniter 4'ün görsel servisi varsayılan olarak GD sürücüsünü kullanır (`Config\Images::$defaultHandler` değeri `gd`); `service('image')` ile bir küçük resim üretebiliyorsanız web tarafı da hazırdır.

GD görseli işlerken bellekte sıkıştırılmamış hâlde tutar ve kabaca genişlik × yükseklik × 4 bayt yer kaplar: 10.000 × 10.000 piksellik bir görsel yaklaşık 400 MB demektir ve varsayılan 128 MB'lık `memory_limit` değerini aşar. Kullanıcıdan gelen görselin boyutunu işlemeden önce `getimagesize()` ile kontrol edin; yükleme ucunun geri kalanı için [CodeIgniter'da güvenli dosya yükleme](https://cilginyazilim.com/blog/adim-adim-guvenli-dosya-yukleme-codeigniter) yazısına bakın.

> Aynı kontrol için sık önerilen `phpinfo()` sayfası ortam değişkenlerini düz metin gösterir: Docker'da `-e DB_PASSWORD=…` ile verilen bir parola da orada görünür. Hangi yöntemi seçerseniz seçin, kontrol dosyasını iş bitince silin; canlı sunucuda bırakmayın.

GD kurulumundaki asıl tuzak eklentinin yokluğu değil, düzenlenen php.ini dosyasının PHP'nin okuduğu dosya olmamasıdır. Önce `php --ini` ile okunan php.ini dosyasını bulun, Windows'ta `extension=gd` satırını açın, Linux'ta PHP sürümünüzle aynı paketi kurun, Docker'da bağımlılıklarıyla derleyin ve her değişiklikten sonra hem komut satırını hem web tarafını test edin. Composer kontrolünü susturmak yerine eklentiyi açın; ekipte herkesin aynı eklentilerle çalışması için [yerel geliştirme ortamını tek komutla kurmak](https://cilginyazilim.com/blog/yerel-gelistirme-ortamini-tek-komutla-kurmak) iyi bir sonraki adımdır.

Konunun derinlemesine anlatımı için: [PHP Kılavuzu — GD Installation](https://www.php.net/manual/en/image.installation.php).

## Sıkça Sorulan Sorular

### GD mi Imagick mi kullanmalıyım?

Çoğu web işi için GD yeter; Windows derlemelerinde PHP ile gelir, Linux'ta ayrı paket olarak kurulur. Imagick daha fazla biçim ve daha gelişmiş işlem sunar, ama sunucuya ImageMagick kurulmasını gerektirir. Kütüphaneniz ikisini de destekliyorsa kurulu olanı seçin.

### Eklentiyi açtım ama phpinfo() hâlâ göstermiyor, neden?

Büyük olasılıkla web sunucusu yeniden başlatılmadı ya da düzenlediğiniz dosya web tarafının okuduğu dosya değil. phpinfo() çıktısının başındaki "Loaded Configuration File" satırı, web tarafının gerçekten hangi dosyayı okuduğunu gösterir.

### gd_info() WebP desteği için neden false dönüyor?

GD, derlenirken WebP kütüphanesi olmadan kurulmuş. XAMPP 8.2 ile gelen hazır DLL'de destek açıktır. Docker'da libwebp-dev paketini kurup gd'yi --with-webp seçeneğiyle yeniden derlemeniz gerekir.

### Paylaşımlı hostingde GD'yi nasıl açarım?

php.ini dosyasına erişiminiz yoksa kontrol panelindeki PHP ayarlarından eklenti listesinde gd'yi işaretleyin; CloudLinux kullanan birçok cPanel sunucusunda bu ekranın adı "Select PHP Version"dır. Bu seçenek yoksa barındırma firmasından açmasını isteyin.

---

Kaynak: [PHP GD Extension Nasıl Etkinleştirilir? XAMPP, Linux ve Docker](https://cilginyazilim.com/blog/php-gd-extension-nasil-etkinlestirilir)
