PHP upload_max_filesize Explained: Configuration, Limits, and Best Practices

Introduction

The upload_max_filesize directive controls the maximum size of a file that PHP allows users to upload. It is one of the most important PHP settings for websites that support file uploads, such as WordPress, Laravel, content management systems, and custom PHP applications.

If a user attempts to upload a file larger than the configured limit, PHP rejects the request before the application processes it.

This guide explains how upload_max_filesize works, how to change it, recommended values for different use cases, and common issues that prevent changes from taking effect.

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

The upload_max_filesize directive defines the maximum size of an individual uploaded file.

Example:

upload_max_filesize = 20M

This configuration allows users to upload files up to 20 MB.

If a file exceeds this limit, PHP rejects the upload and the application receives an upload error.

How File Upload Limits Work

Several PHP directives work together during a file upload.

Browser
    │
    ▼
PHP
    │
    ├── upload_max_filesize
    ├── post_max_size
    ├── max_file_uploads
    └── memory_limit
    │
    ▼
Application

If any of these limits are exceeded, the upload may fail.

Check the Current Setting

Run:

php -i | grep upload_max_filesize

Example:

upload_max_filesize => 20M => 20M

Find the Active php.ini File

Locate the configuration file:

php --ini

Example output:

Loaded Configuration File: /etc/php.ini

For PHP-FPM, make sure you modify the configuration file used by the web server, not only the CLI configuration.

Change upload_max_filesize

Open the PHP configuration file:

sudo nano /etc/php.ini

Find:

upload_max_filesize = 2M

Change it to:

upload_max_filesize = 100M

Save the file.

Restart PHP-FPM

Apply the changes:

sudo systemctl restart php-fpm

Check the service status:

sudo systemctl status php-fpm

Expected output:

Active: active (running)

Verify the New Value

Run:

php -i | grep upload_max_filesize

Or create a PHP file:

<?php
phpinfo();

Search for:

upload_max_filesize

The displayed value should match the updated configuration.

Recommended Values

| Application     |       Recommended Value |
| --------------- | ----------------------- |
| Small websites  |                 10M–20M |
| WordPress       |                64M–128M |
| Image galleries |                    128M |
| Video uploads   |          256M or higher |
| Development     | Depends on requirements |

Avoid setting the value much higher than necessary, as excessively large uploads may consume server resources and increase upload times.

upload_max_filesize vs post_max_size

Many administrators increase only upload_max_filesize.

However, uploads can still fail if post_max_size is smaller.

Example:

upload_max_filesize = 100M

post_max_size = 128M

A good rule is:

post_max_size should always be larger than upload_max_filesize.

This allows room for form fields and request overhead in addition to the uploaded file itself.

Common Error Messages

A common PHP upload error is:

The uploaded file exceeds the upload_max_filesize directive in php.ini

Possible causes include:

The file exceeds the configured limit.

PHP-FPM has not been restarted.

The wrong php.ini file was modified.

post_max_size is smaller than upload_max_filesize.

Nginx or Apache has its own upload size limit.

Nginx Upload Limit

Even if PHP allows large uploads, Nginx may reject them first.

Example:

client_max_body_size 100M;

If this value is smaller than the uploaded file, Nginx returns 413 Request Entity Too Large before the request reaches PHP.

Best Practices

Set upload_max_filesize according to your application's requirements.

Configure post_max_size to be larger than upload_max_filesize.

Verify Nginx or Apache upload limits.

Restart PHP-FPM after changing the configuration.

Test uploads after modifying the settings.

Conclusion

The upload_max_filesize directive controls the maximum size of files that PHP accepts during uploads. Correctly configuring this setting, together with post_max_size and your web server's upload limit, helps ensure reliable file uploads while protecting server resources.

When troubleshooting upload failures, always check the complete upload pipeline rather than focusing on a single configuration value.