PHP 8.5 web development and deployment tutorial series

This tutorial explains how to install Composer on Ubuntu 24.04 securely by downloading the official installer and verifying its current SHA-384 checksum before execution. You will install the required PHP command-line tools, configure Composer globally or for your current user, run diagnostics, update or remove Composer, and fix common PATH, permission, and PHP extension errors.

The procedure deliberately does not hard-code a Composer release number or installer checksum. Composer releases and installer signatures change. Instead, the commands retrieve the current checksum from Composer’s official checksum endpoint immediately before downloading and verifying the installer.

If PHP is not installed yet, begin with How to Install PHP 8.3 on Ubuntu 24.04. Ubuntu 24.04 provides PHP 8.3 through its standard repositories, which is suitable for current Composer releases and modern PHP projects.

Table of Contents

Prerequisites

  • An Ubuntu 24.04 LTS system with network access to getcomposer.org and composer.github.io.
  • A normal user account with sudo permission for package installation and the optional system-wide binary copy.
  • A POSIX-compatible shell such as Bash.
  • Correct system time and working TLS certificate validation.

Confirm the operating system and architecture:

cat /etc/os-release
dpkg --print-architecture
date -Is

The commands below install Composer itself from the official Composer installer. They use Ubuntu packages only for PHP CLI, curl, unzip, and supporting certificate files.

Install PHP CLI, unzip, and curl on Ubuntu 24.04

Refresh APT metadata and install the required packages:

sudo apt update
sudo apt install --yes php-cli curl unzip ca-certificates

Verify that the commands resolve from the expected PATH:

php --version
php --ini
curl --version
unzip -v

Composer uses the PHP CLI configuration, not PHP-FPM’s configuration. The output of php --ini identifies the configuration files loaded by Composer. If the CLI and website report different PHP versions or extensions, inspect them separately.

Download the Official Composer Installer and Verify SHA-384

Use a private temporary directory owned by the current user:

COMPOSER_INSTALL_DIR="$(mktemp -d)"
cd "$COMPOSER_INSTALL_DIR"
pwd

Retrieve the current installer checksum from Composer’s official checksum endpoint:

curl --fail --silent --show-error --location 
  https://composer.github.io/installer.sig 
  --output composer-installer.sig

EXPECTED_CHECKSUM="$(tr -d 'rn' < composer-installer.sig)"
printf '%sn' "$EXPECTED_CHECKSUM"

Download the official installer over HTTPS:

curl --fail --silent --show-error --location 
  https://getcomposer.org/installer 
  --output composer-setup.php

Calculate the SHA-384 checksum locally and compare it with the value retrieved from Composer:

ACTUAL_CHECKSUM="$(php -r "echo hash_file('sha384', 'composer-setup.php');")"

if [ "$EXPECTED_CHECKSUM" != "$ACTUAL_CHECKSUM" ]; then
  printf '%sn' 'ERROR: Composer installer checksum mismatch.' >&2
  rm -f composer-setup.php composer-installer.sig
  exit 1
fi

printf '%sn' 'Composer installer checksum verified.'

If the values differ, stop. Do not run the installer and do not copy a checksum from an old tutorial. Remove the files, confirm system time, DNS, TLS interception, and proxy configuration, and then download both files again from the official endpoints.

The verified installer checks PHP settings and downloads the current stable composer.phar. The checksum verified above authenticates the installer script, not every future Composer release forever.

Install Composer Globally in /usr/local/bin

Run the verified installer as your normal user to create the PHAR in the temporary directory:

php composer-setup.php --filename=composer.phar

Use install with elevated privileges only for the final copy into the system-wide PATH:

sudo install --owner=root --group=root --mode=0755 
  composer.phar /usr/local/bin/composer

Clean up the downloaded installer, checksum, and temporary PHAR:

rm -f composer-setup.php composer-installer.sig composer.phar
cd /
rmdir "$COMPOSER_INSTALL_DIR"
unset COMPOSER_INSTALL_DIR EXPECTED_CHECKSUM ACTUAL_CHECKSUM

On a standard Ubuntu installation, /usr/local/bin is already in the PATH. A system-wide binary is convenient when several normal users need the same Composer executable. Project dependency files and caches still belong to the user running Composer.

Current-User Composer Installation Alternative

If you do not have sudo access or do not want a system-wide executable, install Composer under ~/.local/bin. Repeat the verified download procedure above, then run:

mkdir -p "$HOME/.local/bin"

php composer-setup.php 
  --install-dir="$HOME/.local/bin" 
  --filename=composer

chmod 0755 "$HOME/.local/bin/composer"

Add that directory to PATH only if it is not already present:

case ":$PATH:" in
  *":$HOME/.local/bin:"*) ;;
  *) printf 'nexport PATH="$HOME/.local/bin:$PATH"n' >> "$HOME/.profile" ;;
esac

. "$HOME/.profile"

Remove the installer artifacts after successful installation:

rm -f composer-setup.php composer-installer.sig

This method keeps the Composer binary and its updates under the current user’s control. Other users will not automatically receive the command.

Verify the Composer Installation

Resolve the executable and display its version without assuming a particular current release:

command -v composer
type -a composer
composer --version
composer --version --no-ansi

Run Composer’s diagnostic checks:

composer diagnose

composer diagnose checks common configuration, connectivity, keys, Git settings, disk space, and Composer-related environment problems. Read every warning in context; do not treat a successful version command as proof that project dependencies can be installed.

Inspect the PHP environment Composer sees:

composer show --platform
php --version
php --ini
php -m

Global Composer Installation vs Project Dependencies

A globally accessible Composer binary and globally installed Composer packages are different concepts:

  • Global Composer binary: /usr/local/bin/composer or ~/.local/bin/composer lets the shell run Composer from any directory.
  • Project dependencies: packages declared in a project’s composer.json and locked in composer.lock. Composer installs them into the project’s vendor/ directory.
  • Composer global packages: packages installed with composer global require into Composer’s global home. Use these sparingly because they are not pinned by each project.

For application deployments, commit composer.json and composer.lock, then install the reviewed lock file:

cd /srv/example-app
composer validate --strict
composer install --no-dev --prefer-dist --no-interaction 
  --optimize-autoloader

Do not replace composer install with composer update during production deployment. install follows the lock file; update resolves new dependency versions and rewrites it.

To understand namespaces and generated autoload files, continue with PHP Namespaces and PSR-4 Autoloading Explained.

Update Composer Safely

Check the installed binary and run diagnostics before updating:

command -v composer
composer --version
composer diagnose

Update a current-user installation

composer self-update
composer --version
composer diagnose

If the new Composer binary causes an unexpected compatibility problem, Composer supports rolling back the most recent self-update:

composer self-update --rollback

Update a system-wide installation

A binary owned by root in /usr/local/bin cannot normally replace itself as an unprivileged user. The most auditable approach is to repeat the verified installer workflow and use sudo install only to replace the final binary.

Composer also supports self-update with elevated filesystem permission:

sudo composer self-update
composer --version
composer diagnose

Use elevated self-update only for the trusted Composer binary itself, outside a project directory. Do not run dependency installation, project scripts, or third-party plugins as root.

Updating Composer does not update project dependencies. Review dependency changes separately with the project’s tests, static analysis, and security checks. See PHP Code Quality with PHPStan, PHP-CS-Fixer, and Composer Audit.

Uninstall Composer

First identify every Composer executable that the shell can find:

type -a composer
command -v composer

For the system-wide installation used in this tutorial:

sudo rm -f /usr/local/bin/composer
hash -r
command -v composer || true

For the current-user alternative:

rm -f "$HOME/.local/bin/composer"
hash -r
command -v composer || true

Removing the Composer executable does not remove a project’s composer.json, composer.lock, or vendor/. Do not delete project dependencies or Composer caches unless that separate cleanup is intentional.

Common Composer Installation Errors

Fix “composer: command not found”

Check whether the binary exists and which PATH the current shell uses:

command -v composer || true
type -a composer || true
ls -l /usr/local/bin/composer
ls -l "$HOME/.local/bin/composer"
printf '%sn' "$PATH"

If Composer is installed under ~/.local/bin, add it to ~/.profile and reload the profile as shown earlier. For systemd, cron, CI, or another user, configure PATH explicitly; those environments do not necessarily read your interactive profile.

Clear the shell’s remembered command location after moving or replacing Composer:

hash -r
composer --version

Fix permission denied during global installation

Do not make /usr/local/bin world-writable. Confirm the directory and use sudo only for the final copy:

ls -ld /usr/local/bin
ls -l /usr/local/bin/composer
sudo install --owner=root --group=root --mode=0755 
  composer.phar /usr/local/bin/composer

If project installation fails with a permission error, inspect the project rather than running Composer as root:

namei -l /srv/example-app
find /srv/example-app -maxdepth 2 
  ! -user "$(id -un)" -ls

Correct only the confirmed project owner and group according to your deployment model. Avoid broad chmod -R 777 or recursive ownership changes without reviewing the exact target.

Diagnose missing PHP extensions

Composer reports missing platform requirements using names such as ext-curl, ext-mbstring, ext-xml, or ext-zip. Inspect the CLI configuration and loaded modules:

php --version
php --ini
php -m | sort
composer show --platform

Inside an existing project, check requirements against the installed platform:

composer check-platform-reqs
composer diagnose

Search Ubuntu 24.04 packages for the exact extension reported by Composer:

apt search php8.3-
apt show php8.3-curl
apt show php8.3-mbstring
apt show php8.3-xml
apt show php8.3-zip

Install only the extensions required by the application, for example:

sudo apt install php8.3-curl php8.3-mbstring php8.3-xml php8.3-zip
php -m | grep -E 'curl|mbstring|xml|zip'
composer check-platform-reqs

PHP CLI and PHP-FPM may load different configuration directories. This tutorial diagnoses Composer through the CLI. Restarting PHP-FPM is not required for Composer itself, although a web application may need its FPM service reloaded after adding an extension.

Checksum mismatch

Do not execute the downloaded installer. Delete both local files and fetch the checksum and installer again:

rm -f composer-setup.php composer-installer.sig
date -Is
curl -I https://composer.github.io/installer.sig
curl -I https://getcomposer.org/installer

Investigate incorrect system time, a proxy, TLS interception, a partial download, local file modification, or an endpoint other than the official Composer domains.

Composer cannot download packages

Separate DNS, TLS, proxy, Git, and authentication problems:

getent hosts repo.packagist.org
curl -I --connect-timeout 5 https://repo.packagist.org/
git --version
composer diagnose
env | grep -E '^(HTTP|HTTPS|NO)_PROXY='

Do not disable TLS verification as a workaround. Correct the CA trust store, proxy, DNS, credentials, or system time.

Why Composer Should Generally Not Run as Root

Composer plugins and project scripts can execute third-party code with the privileges of the user running Composer. Running composer install or composer update as root can therefore give dependency-controlled code unrestricted access to the host and can leave project files owned by root.

Use a normal deployment or application user for project operations:

cd /srv/example-app
id
composer install

If you must inspect an untrusted package definition, disabling plugins and scripts reduces risk but does not make dependency code safe to execute:

composer install --no-plugins --no-scripts

Containers do not automatically justify running Composer as root. Use a non-root build user where practical and copy reviewed artifacts into the runtime image. For a complete multi-service example, see Run PHP, Nginx, MySQL, and Redis with Docker Compose.

Final Composer Verification Checklist

  • Ubuntu reports version 24.04 from /etc/os-release.
  • php --version, curl --version, and unzip -v run successfully.
  • The installer was downloaded only from https://getcomposer.org/installer.
  • The expected checksum was retrieved from https://composer.github.io/installer.sig.
  • The local SHA-384 value matched before the installer ran.
  • command -v composer points to the intended global or user path.
  • composer --version runs without assuming a hard-coded current release.
  • composer diagnose has been reviewed.
  • Project Composer commands run as a normal user, not root.
  • The project passes composer validate --strict and relevant tests.
  • Production deployment uses the reviewed composer.lock.
  • Temporary installer files have been removed.

Frequently Asked Questions

What is the recommended way to install Composer on Ubuntu 24.04?

Download the official Composer installer, retrieve the current installer SHA-384 checksum from Composer’s official checksum endpoint, compare it locally, and run the installer only when the values match. Put the resulting executable in /usr/local/bin for a system-wide command or ~/.local/bin</code for one user.

Can I install Composer with APT?

Ubuntu may provide a Composer package, but its release cadence can differ from upstream Composer. This tutorial uses Composer's official verified installer so the executable can follow Composer's maintained release channel. Choose one installation method and avoid leaving multiple Composer executables in PATH.

Does installing Composer globally install project packages globally?

No. A global binary only makes the composer command accessible. Running composer install in a project installs packages described by that project's lock file into its project directory.

Should composer.lock be committed?

Commit composer.lock for applications so development, CI, and production install reviewed versions. Reusable libraries commonly commit composer.json while allowing consuming applications to resolve the final dependency set.

How do I install Composer without sudo?

Install it in ~/.local/bin/composer and ensure that directory appears in the current user's PATH. No system directory needs to be modified.

How often should Composer be updated?

Monitor Composer security and maintenance releases and update through a tested operational process. Check the binary version and run composer diagnose after updating. Project dependency updates are a separate change that requires lockfile review and tests.

Why does Composer report a missing extension when the website works?

Composer runs with PHP CLI, while the website commonly runs PHP-FPM. They can use different PHP versions, configuration directories, and enabled extensions. Diagnose Composer with php --ini and php -m in the same shell.

Conclusion

You now know how to install Composer on Ubuntu 24.04 securely without hard-coding an obsolete checksum or release number. Retrieve the current installer checksum from Composer, verify SHA-384 before execution, install the executable with narrow privileges, and run project dependency operations as a normal user. Finish with composer diagnose, platform requirement checks, application tests, and lockfile review.

Official References

Similar Posts

Leave a Reply

Your email address will not be published. Required fields are marked *