---
title: Using multiple PHP & Composer versions on MacOS
url: https://calvin.my/posts/using-multiple-php-composer-versions-on-macos
published: 2024-09-27
updated: 2026-09-17
category: Development
tags:
- PHP
- composer
- MacOS
- Homebrew
summary: The post explains how to manage multiple PHP versions on macOS by selecting a default through shell PATH settings, changing it temporarily per terminal session, or invoking a specific installed version directly. It warns that projects may behave unexpectedly under incompatible PHP releases. Because Composer is tied to its PHP runtime, users should reinstall the global Composer when upgrading PHP and create project-local Composer installations for older projects, excluding them from version control.
---

# Using multiple PHP & Composer versions on MacOS

Refers to the previous post on how to install/upgrade PHP:

[https://calvin.my/posts/install-upgrade-php-in-macos](../posts/install-upgrade-php-in-macos)

* * *

## Use default version

1. To check the default PHP version on your machine:

   ```bash
   % which php
   /opt/homebrew/opt/php@8.3/bin/php
   ```

2. With above configuration, whenever you enter "php xxxxxxx" in your terminal, it executes php@8.3

3. If your application is built for a different PHP version (e.g. 8.1), running it with the default PHP might cause unexpected behaviors.
* * *
## Change default version

1. Edit \~/.zshrc (on a mac)

2. Comment / uncomment the version you need

   ```bash
   # export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"
   # export PATH="/opt/homebrew/opt/php@8.3/sbin:$PATH"
   export PATH="/opt/homebrew/opt/php@8.4/bin:$PATH"
   export PATH="/opt/homebrew/opt/php@8.4/sbin:$PATH"
   ```

3. Save and reload

   ```bash
   source ~/.zshrc
   ```
* * *
## Change default version (Temporarily)

1. Directly set the PATH for a terminal session.

   ```bash
   export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"
   ```

2. This uses PHP 8.3 until you close the terminal session.
* * *
## Directly use non-default versions

1. To check all the PHP versions you have on your machine:

   ```bash
   % ls /opt/homebrew/opt | grep php
   php
   php@7.4
   php@8.0
   php@8.1
   php@8.2
   php@8.3
   ```

2. You can pick the correct version you need and run it with:

   ```bash
   % /opt/homebrew/opt/php@8.1/bin/php <command>

   % /opt/homebrew/opt/php@8.1/bin/php -v
   PHP 8.1.29 (cli) (built: Jun  5 2024 05:51:57) (NTS)
   Copyright (c) The PHP Group
   Zend Engine v4.1.29, Copyright (c) Zend Technologies
       with Zend OPcache v8.1.29, Copyright (c), by Zend Technologies
   ```

* * *

## PHP Composer

1. Composer is the tool in PHP to manage dependencies. For example, it is used in a Laravel application.

2. Composer is tied to PHP versions. That means setup composer with PHP 8.1 and later executing it using PHP 8.3, might not work properly.

3. In the composer [installation guide](https://getcomposer.org/download/), the steps create a global composer executable.&nbsp;When you complete the installation steps following the guide, you get a default composer compatible with your PHP.

   ![](https://camy-pub.s3.ap-southeast-1.amazonaws.com/3f843cdb-751a-4e19-83aa-14993c4a009c.png)

4. You should do this once every time you install a newer PHP version on your machine.

* * *

## Using non-default composer version

Now that you have replaced the default composer, what happens to the older projects?

1. Go to your project directory.

2. Follow the same composer installation guide, but replace all the "php" command with the exact version you need. e.g.

   ```bash
   % php composer-setup.php

   % /opt/homebrew/opt/php@8.1/bin/php composer-setup.php
   ```

3. This gives you a "composer.phar" executable in the project directory.&nbsp;

   ![](https://camy-pub.s3.ap-southeast-1.amazonaws.com/cde34d9e-bdbd-4efa-b367-4e1889fe421e.png)

4. Do not run the final step to copy this as default.

   ![](https://camy-pub.s3.ap-southeast-1.amazonaws.com/c1e67001-cebc-4c62-8633-54d4ced847a5.png)

5. Now you can use the correct version of composer. e.g.

   ```bash
   // This runs composer (for 8.1) using php 8.1
   % /opt/homebrew/opt/php@8.1/bin/php composer.phar install

   // This runs composer (for 8.3) using php 8.3
   % composer install
   ```

   Note: Add composer.phar into your gitignore so it won't go into your repository.