PHP opcache.max_accelerated_files Explained: Configuration, Performance, and Best Practices

Introduction

The opcache.max_accelerated_files directive defines the maximum number of PHP scripts that OPcache can store in its hash table. It plays an important role in determining how efficiently OPcache caches compiled bytecode for your application.

If this value is too low, some scripts cannot be cached, resulting in unnecessary recompilation and reduced performance. Choosing an appropriate value helps improve cache hit rates and reduces CPU usage on busy servers.

This guide explains how opcache.max_accelerated_files works, how to configure it, recommended values for different applications, and common performance considerations.

Test Environment

Operating System : AlmaLinux 10
PHP Version      : PHP 8.3
Web Server       : Nginx
PHP-FPM          : Enabled
Architecture     : x86_64
Last Tested      : July 2026

What Is opcache.max_accelerated_files?

Every PHP script cached by OPcache occupies one entry in the OPcache hash table.

The opcache.max_accelerated_files directive determines the maximum number of cached script entries.

Example:

opcache.max_accelerated_files = 10000

With this configuration, OPcache can store information for approximately 10,000 PHP scripts before reaching its configured limit.

How OPcache Stores Scripts

Without OPcache:

Request
    │
    ▼
Read PHP File
    │
    ▼
Compile Script
    │
    ▼
Execute

Every request recompiles the PHP file.

With OPcache enabled:

Request
    │
    ▼
OPcache Lookup
    │
 ┌──┴──────────┐
 │             │
Cache Hit   Cache Miss
 │             │
 ▼             ▼
Execute     Compile
Bytecode       │
               ▼
        Store Script

The hash table created by opcache.max_accelerated_files determines how many compiled scripts OPcache can track efficiently.

Check the Current Value

Run:

php -i | grep opcache.max_accelerated_files

Example:

opcache.max_accelerated_files => 10000 => 10000

Locate the Active Configuration File

Check which configuration file is being used.

php --ini

Many Linux distributions load OPcache settings from:

/etc/php.d/10-opcache.ini

Modify the configuration used by PHP-FPM rather than only the CLI configuration.

Change opcache.max_accelerated_files

Open the OPcache configuration file.

sudo nano /etc/php.d/10-opcache.ini

Locate:

opcache.max_accelerated_files = 10000

Example:

opcache.max_accelerated_files = 40000

Save the file.

Restart PHP-FPM

Restart PHP-FPM to apply the changes.

sudo systemctl restart php-fpm

Verify the service:

sudo systemctl status php-fpm

Expected output:

Active: active (running)

Verify the Configuration

Run:

php -i | grep opcache.max_accelerated_files

Or use:

<?php
phpinfo();

Search for:

opcache.max_accelerated_files

Recommended Values

| Application                   | Recommended Value |
| ----------------------------- | ----------------- |
| Small websites                |              4000 |
| WordPress                     |             10000 |
| Laravel                       |             20000 |
| Symfony                       |             20000 |
| Magento                       |             40000 |
| Large enterprise applications |      50000–100000 |

The ideal value depends on the number of PHP files loaded by your application and its dependencies.

What Happens If the Value Is Too Low?

When the number of cached scripts exceeds the configured limit, OPcache cannot cache every file.

Possible consequences include:

Lower cache hit rates.

More PHP recompilation.

Increased CPU usage.

Slower response times.

Reduced scalability under heavy traffic.

What Happens If the Value Is Too High?

Setting a very large value generally has little negative impact, but it slightly increases the memory required for OPcache's internal hash table.

For most servers, allocating more entries than currently required is acceptable, provided sufficient memory is available.

opcache.max_accelerated_files vs opcache.memory_consumption

These directives control different aspects of OPcache.

| Directive                       | Purpose                                              |
| ------------------------------- | ---------------------------------------------------- |
| `opcache.memory_consumption`    | Amount of shared memory reserved for cached bytecode |
| `opcache.max_accelerated_files` | Maximum number of cached PHP script entries          |

Example:

opcache.memory_consumption = 256

opcache.max_accelerated_files = 20000

Increasing the number of cached script entries without allocating enough shared memory may still lead to cache exhaustion.

Both settings should be adjusted together.

Relationship with Other OPcache Settings

Several OPcache directives work together to improve PHP performance.

PHP Request
      │
      ▼
OPcache
      │
      ├── memory_consumption
      ├── max_accelerated_files
      ├── validate_timestamps
      ├── revalidate_freq
      └── enable
      │
      ▼
Execute Script

Optimizing only one directive may not achieve the best performance.

Common Issues

Cache Hit Rate Is Low

Possible causes include:

opcache.max_accelerated_files is too small.

OPcache memory is exhausted.

Frequent application deployments invalidate the cache.

OPcache is disabled.

New Scripts Are Not Cached

Applications with thousands of PHP files may exceed the configured limit.

Increasing opcache.max_accelerated_files allows OPcache to store additional compiled scripts.

Performance Does Not Improve

If increasing the value has little effect, consider checking:

opcache.memory_consumption

opcache.validate_timestamps

opcache.revalidate_freq

Database performance

Disk I/O bottlenecks

Performance tuning should be based on the overall system rather than a single configuration option.

Best Practices

Allocate enough script entries for your application.

Monitor OPcache usage with opcache_get_status() or server monitoring tools.

Tune opcache.memory_consumption and opcache.max_accelerated_files together.

Restart PHP-FPM after changing OPcache settings.

Reevaluate the configuration after major application upgrades or framework changes.

Conclusion

The opcache.max_accelerated_files directive determines how many compiled PHP scripts OPcache can manage efficiently. Choosing an appropriate value helps maximize cache coverage, reduce unnecessary recompilation, and improve application performance.

For modern PHP applications that include thousands of framework and Composer files, increasing this value alongside opcache.memory_consumption is an important step in optimizing production environments.