In PHP, chroot() changes the process root directory to a folder you choose. After that, the script cannot see anything outside that folder, and '/' now means the new folder.
chroot() is a Unix feature used to build a simple 'jail' around a program. It is very limited in PHP. It only exists when PHP runs as CLI, CGI or Embed (not as a web server module), it needs root privileges, it does not exist on Windows, and it is not available in thread-safe (ZTS) builds. For this reason, most beginners will never need it. It returns true on success and false on failure.
Syntax
Call chroot() with the values you need. Start with this line.
PHP
if (chroot($jail)) { chdir('/'); }
Call
What it does
chroot('/var/jail')
Makes /var/jail the new root for the script. Needs root privileges on a Unix system.
chroot($jail) && chdir('/')
Changes the root and then moves into it, which is the recommended pattern.
function_exists('chroot')
Checks whether chroot() is available before you try to call it.
Always call chdir('/') right after a successful chroot(). Without it, the working directory may still point outside the jail. After chroot(), the old paths are gone for good, so do your other setup first.
Library declarations
PHP
chroot(string $directory): bool
Parameters
Parameter
Description
directory
Required. The path of the folder that should become the new root directory.
Return Value
Return Value
Description
bool
Returns true on success and false on failure, for example when the folder does not exist or the script does not have root privileges. A warning is also raised on failure.
PHP Examples
Example 1 — Checking If chroot() Is Available
Instead of calling chroot() blindly, we first check the operating system and whether the function exists. On Windows the demo simply skips.
PHP
<?php
if (PHP_OS_FAMILY === 'Windows' || !function_exists('chroot')) {
echo "chroot() is not available on this system. Skipping the demo.", PHP_EOL;
} else {
echo "chroot() is available (SAPI: ", PHP_SAPI, ")", PHP_EOL;
}
Output
chroot() is not available on this system. Skipping the demo.
How It Works
PHP_OS_FAMILY tells us the operating system family, such as Windows or Linux.
function_exists('chroot') is false on Windows and in builds where the function is not compiled in.
The output shown here is what you would see on Windows. On Linux with the CLI, you would see: chroot() is available (SAPI: cli).
Being available does not mean it will work. Calling it still needs root privileges.
Example 2 — A Failing chroot() Call
We point chroot() at a folder that does not exist. This always fails, so the demo is safe even on a system where PHP runs as root.
PHP
<?php
if (PHP_OS_FAMILY === 'Windows' || !function_exists('chroot')) {
echo "chroot() is not available on this system. Skipping the demo.", PHP_EOL;
} else {
$ok = @chroot(__DIR__ . '/no-such-jail');
if ($ok === false) {
echo "chroot() failed. The root directory was not changed.", PHP_EOL;
} else {
echo "chroot() worked.", PHP_EOL;
}
}
Output
chroot() is not available on this system. Skipping the demo.
How It Works
The first if block skips the demo on systems without chroot(). The output above is the Windows result.
On Linux or macOS, the folder 'no-such-jail' does not exist, so chroot() returns false.
That would print: chroot() failed. The root directory was not changed.
We compare with === false, so a real failure is never mistaken for success.
Example 3 — A Requirements Checklist
chroot() has several requirements. This small checklist prints each one, so you can see why the function might not work on your machine.
PHP
<?php
$checks = [
'Not Windows' => PHP_OS_FAMILY !== 'Windows',
'chroot() exists' => function_exists('chroot'),
'CLI, CGI or Embed' => in_array(PHP_SAPI, ['cli', 'cgi', 'cgi-fcgi', 'embed'], true),
];
foreach ($checks as $label => $ok) {
echo $label, ": ", $ok ? 'yes' : 'no', PHP_EOL;
}
if (in_array(false, $checks, true)) {
echo "Skipping chroot() on this system.", PHP_EOL;
} else {
echo "Requirements met. Root privileges are still needed.", PHP_EOL;
}
Output
Not Windows: no
chroot() exists: no
CLI, CGI or Embed: yes
Skipping chroot() on this system.
How It Works
The $checks array pairs a short label with a true or false test.
foreach prints each label with yes or no. The output shown is from Windows running the CLI.
in_array(false, $checks, true) is true when at least one requirement failed.
Even when every line says yes, chroot() still fails unless the script runs with root privileges.
Frequently Asked Questions
It changes the root directory of the running PHP process. After a successful call, the folder you passed becomes '/', and the script can no longer reach files outside it.
The most common reasons are: you are on Windows, PHP is running as a web server module, the build is thread-safe (ZTS), or the script does not run as root. chroot() needs all of these conditions to be right.
Almost never. Web requests usually run without root privileges and not in the CLI, CGI or Embed setup that chroot() requires. It is meant for command line tools and special server setups.
Yes. Call chdir('/') right after a successful chroot() so the working directory is inside the new root. Otherwise relative paths might still point outside the jail.
No. It limits which files the process can see, but it does not stop a process that is running as root from escaping. Treat it as one layer of protection and use proper permissions, containers or users as well.