PHP max_file_uploads Explained: Configuration, Limits, and Best Practices

Introduction

The max_file_uploads directive defines the maximum number of files that PHP accepts during a single file upload request. It is designed to prevent excessively large multipart uploads from consuming unnecessary server resources.

Unlike upload_max_filesize, which limits the size of an individual file, max_file_uploads limits the total number of files that can be uploaded in one request.

This guide explains how max_file_uploads works, how to configure it, recommended values for different applications, and common issues that occur when the upload count exceeds the configured limit.

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 max_file_uploads?

The max_file_uploads directive specifies the maximum number of uploaded files PHP processes in a single request.

Example:

max_file_uploads = 20

With this configuration, a user can upload up to 20 files in one HTTP request.

If the request contains more than 20 files, PHP ignores any files beyond the configured limit.

How max_file_uploads Works

Suppose a user selects multiple files using an HTML form.

Browser
    │
    ▼
30 Selected Files
    │
    ▼
PHP
    │
max_file_uploads = 20
    │
    ├── Files 1–20 → Accepted
    └── Files 21–30 → Ignored

Only the first 20 uploaded files are processed.

Check the Current Value

Run:

php -i | grep max_file_uploads

Example output:

max_file_uploads => 20 => 20

Locate the Active php.ini File

php --ini

Example:

Loaded Configuration File: /etc/php.ini

For PHP-FPM deployments, make sure you edit the configuration file used by PHP-FPM.

Change max_file_uploads

Open the PHP configuration file.

sudo nano /etc/php.ini

Find:

max_file_uploads = 20

Example:

max_file_uploads = 50

Save the file.

Restart PHP-FPM

Apply the new configuration.

sudo systemctl restart php-fpm

Verify:

sudo systemctl status php-fpm

Expected output:

Active: active (running)

Verify the Configuration

Run:

php -i | grep max_file_uploads

Or create:

<?php
phpinfo();

Search for:

max_file_uploads

The displayed value should match your configuration.

max_file_uploads vs upload_max_filesize

These directives control different aspects of file uploads.

| Directive             | Purpose                                      |
| --------------------- | -------------------------------------------- |
| `max_file_uploads`    | Maximum number of uploaded files per request |
| `upload_max_filesize` | Maximum size of each uploaded file           |

Example:

max_file_uploads = 20

upload_max_filesize = 50M

This configuration allows a maximum of 20 files, with each file up to 50 MB.

max_file_uploads vs post_max_size

post_max_size limits the total size of the entire POST request.

Example:

max_file_uploads = 20

upload_max_filesize = 20M

post_max_size = 256M

Even if the number of uploaded files is below the configured limit, the upload can still fail if the combined request size exceeds post_max_size.

Relationship Between Upload Directives

Browser
    │
    ▼
Nginx
(client_max_body_size)
    │
    ▼
PHP
    │
    ├── max_file_uploads
    ├── upload_max_filesize
    ├── post_max_size
    ├── memory_limit
    └── max_execution_time
    │
    ▼
Application

All of these directives work together to determine whether a file upload succeeds.

Recommended Values

| Application                | Recommended Value |
| -------------------------- | ----------------- |
| Personal website           |                20 |
| WordPress                  |                20 |
| Image gallery              |                50 |
| Document management system |               100 |
| Enterprise applications    |           100–200 |

Choose a value based on your application's expected upload behavior rather than simply using the highest possible limit.

Common Issues

Some Uploaded Files Are Missing

If users upload more files than allowed by max_file_uploads, PHP processes only the permitted number of files. Any additional files are ignored.

Upload Still Fails

Possible causes include:

upload_max_filesize is too small.

post_max_size is too small.

Nginx client_max_body_size is too small.

PHP-FPM has not been restarted.

Large Multi-File Uploads Are Slow

Increasing max_file_uploads only allows more files to be accepted. It does not improve upload speed. Upload performance also depends on network bandwidth, storage performance, and application processing.

Best Practices

Set max_file_uploads according to your application's requirements.

Configure upload_max_filesize and post_max_size appropriately.

Verify web server upload limits such as client_max_body_size.

Restart PHP-FPM after changing configuration values.

Test multi-file uploads after updating the configuration.

Conclusion

The max_file_uploads directive controls the maximum number of files PHP processes in a single upload request. It works together with upload_max_filesize, post_max_size, and your web server configuration to provide a reliable and secure upload process.

Rather than increasing every upload-related limit indiscriminately, configure each directive according to your application's actual requirements. This approach improves reliability while helping protect server resources.