Skip to main content
PsySH can be installed in several ways depending on your needs. Choose the method that works best for your workflow.

​
Requirements

Before installing PsySH, ensure your system meets these requirements:
  • PHP 7.4 or higher (PHP 8.0+ recommended)
  • Required extensions:
    • ext-json (usually enabled by default)
    • ext-tokenizer (usually enabled by default)
PsySH works with PHP 7.4 through PHP 8.x. If you’re using an older version, you’ll need to upgrade PHP first.

​
Optional Extensions

For the best experience, consider installing these optional extensions: 
sudo apt-get install php-pcntl php-posix
The pcntl and posix extensions enable better signal handling, job control, and make PsySH significantly more responsive.

​
Installation Methods

The easiest way to install PsySH is via Composer.
1

Install via Composer

Add PsySH to your project or install it globally:
composer require --dev psy/psysh
2

Run PsySH

After installation, you can run PsySH:
./vendor/bin/psysh
When installed as a project dependency, PsySH automatically detects and uses your project’s autoloader, giving you access to all your classes.

​
Method 2: Download PHAR

For a standalone installation, download the pre-compiled PHAR file.
1

Download the PHAR

Download the latest PsySH PHAR:
wget https://psysh.org/psysh
chmod +x psysh
Or using curl:
curl -L https://psysh.org/psysh -o psysh
chmod +x psysh
2

Move to System Path (Optional)

For global access, move the PHAR to your system path:
sudo mv psysh /usr/local/bin/psysh
Or to a user-local bin directory:
mkdir -p ~/bin
mv psysh ~/bin/psysh
# Add ~/bin to your PATH in ~/.bashrc or ~/.zshrc if not already there
3

Verify Installation

Test that PsySH is working:
psysh --version
You should see output like:
Psy Shell v0.12.20 (PHP 8.2.0 — cli)
The PHAR installation is completely self-contained and doesn’t require Composer. It’s perfect for servers or environments where you want a minimal footprint.

​
Method 3: Manual Installation

For development or contributing to PsySH:
1

Clone the Repository

git clone https://github.com/bobthecow/psysh.git
cd psysh
2

Install Dependencies

composer install
3

Run from Source

./bin/psysh

​
Updating PsySH

​
Update Composer Installation

composer update psy/psysh

​
Update PHAR Installation

If you installed PsySH via PHAR, you can use the built-in self-update command: 
psysh --self-update
The --self-update option is only available when running PsySH from a PHAR file.

​
PHP Manual Installation

For the best experience, download the PHP manual for offline documentation access: 
psysh --update-manual
For a specific language: 
psysh --update-manual=es  # Spanish
psysh --update-manual=fr  # French
psysh --update-manual=ja  # Japanese
Having the PHP manual installed allows you to use the doc command to view function and class documentation directly in PsySH.

​
Verifying Your Installation

Once installed, verify everything is working correctly:
1

Check Version

psysh --version
2

View Environment Info

psysh --info
This displays detailed information about your PsySH configuration, including:
  • PHP version and extensions
  • Configuration file locations
  • History settings
  • Manual database status
  • Available features
3

Test Interactive Mode

Start PsySH and run a simple command:
psysh
Then try:
>>> echo "Hello, PsySH!"
Hello, PsySH!
=> null

​
Command-Line Options

PsySH supports various command-line options: 
psysh [options] [--] [<files>...]

​
Common Options

OptionDescription
-h, --helpDisplay help message
-V, --versionDisplay PsySH version
--infoShow environment and configuration info
-c, --config=FILEUse alternate config file
--cwd=PATHUse alternate working directory
--color / --no-colorForce or disable colors
-i, --interactiveForce interactive mode
-n, --no-interactiveRun without interactive input
--warm-autoloadEnable autoload warming for better tab completion

​
Loading Files

You can load PHP files before starting the shell: 
psysh config.php bootstrap.php
This is useful for:
  • Loading application bootstrappers
  • Setting up test environments
  • Importing utility functions

​
Project Trust

When PsySH detects a local version in your project, it may prompt you about trust: 
# Trust the current project
psysh --trust-project

# Explicitly don't trust (run in restricted mode)
psysh --no-trust-project
PsySH will ask for confirmation before using a project-local version to protect against potentially malicious code. Only trust projects you own or from sources you trust.

​
Next Steps

Quick Start

Learn the basics and start using PsySH

Configuration

Customize PsySH with your preferred settings

Build docs developers (and LLMs) love

Get started for freeTalk to us