Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

imagecreatetruecolor() is undefined because the GD extension is missing

ErrorFatal error: Uncaught Error: Call to undefined function imagecreatetruecolor()

Short answer

All imagecreate* and imagecreatetruecolor functions come from the GD extension. The error means the PHP you are running has not loaded GD. Check with php -m, then install it: php-gd on Ubuntu, docker-php-ext-install gd in the official Docker image, or remove the semicolon from extension=gd in php.ini.

  • Applies to PHP 8.3, Ubuntu 24.04, Docker php 8.x images
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the same PHP that throws the error whether GD is loaded.

    php -m | grep -i gd
  2. 2Match what you see, then jump to its fix

    1. 1php -m prints nothing for gd on a server installed with aptThe GD package is not installed (Ubuntu or Debian)Fix
    2. 2The error appears inside a container built from a php:8.x imageThe official Docker php image was built without GDFix
    3. 3The extension file exists, yet php -m does not list gd (typical on Windows)GD is built or shipped but switched off in php.iniFix

What does the error look like?

  • Fatal error: Uncaught Error: Call to undefined function imagecreatetruecolor()

Cause 1 of 3

The GD package is not installed (Ubuntu or Debian)

1Check

Ubuntu 24.04 ships GD as the php-gd package, which pulls in php8.3-gd.

apt list --installed 2>/dev/null | grep -i php8.3-gd

2Fix

Install the package.

sudo apt install php-gd

3Verify

The function should now exist.

php -r 'var_dump(function_exists("imagecreatetruecolor"));'

Confirmed by packages.ubuntu.com

Did this fix it?

Cause 2 of 3

The official Docker php image was built without GD

1Check

The image does not install extension dependencies for you. GD needs libpng and libjpeg, and FreeType for fonts, installed by hand before the extension is built.

docker run --rm my-image php -m | grep -i gd

2Fix

Install the libraries, configure GD with FreeType and JPEG support, and build it. This is the example in the image documentation.

RUN apt-get update && apt-get install -y \
        libfreetype-dev \
        libjpeg62-turbo-dev \
        libpng-dev \
    && docker-php-ext-configure gd --with-freetype --with-jpeg \
    && docker-php-ext-install -j$(nproc) gd

3Verify

Rebuild the image and list modules again.

docker build -t my-image .
docker run --rm my-image php -m | grep -i gd

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

GD is built or shipped but switched off in php.ini

1Check

The php.ini files shipped with PHP list gd as a commented line. It stays off until the semicolon is removed. extension_dir must also point at the folder that holds the extension DLLs.

php --ini
php -i | grep -i extension_dir

2Fix

Open the php.ini that php --ini reports, remove the leading semicolon so the line reads extension=gd, and restart the web server or PHP process.

; before
;extension=gd
; after
extension=gd

3Verify

Start a new shell and list modules.

php -m | findstr /i gd

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • List needed extensions (ext-gd) in composer.json so a missing one is reported on install.
  • Put the extension install lines in the Dockerfile so every rebuild has GD.
  • After changing php.ini, confirm with php -m instead of assuming.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

PHP cannot turn a hostname into an IP address

Warning: file_get_contents(): php_network_getaddresses: getaddrinfo failed

This warning means the operating system could not resolve the hostname PHP was asked to connect to.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.