WordPress upload_max_filesize vs post_max_size: Which Wins?

On self-hosted WordPress, the maximum upload size is not a WordPress setting — it is whichever is smaller of two PHP directives, upload_max_filesize and post_max_size. That is why the most common advice on this topic ("just raise upload_max_filesize") so often changes nothing at all.

WordPress's own documentation is unusually explicit here, in prose and in core source code. This page quotes both, and nothing else.

The two directives, at a glance

The full sentences, verbatim from the Advanced Administration Handbook's PHP Optimization page:

"The limit on the size of individual file uploads can be configured using the upload_max_filesize php.ini directive."

"The limit on the entire size of a request that can be sent from the web server to PHP for processing can be configured using the post_max_size php.ini directive. The value for post_max_size must be greater than or equal to the value for upload_max_filesize. PHP will not process requests larger in size than the value for post_max_size."

Three things are worth pulling out of that second quote.

First, post_max_size is a limit on the whole request, not on the file inside it. Second, the required relationship is greater than or equal to — equal values are explicitly allowed, so the widely repeated rule that post_max_size "must be larger" overstates what the docs say. Third, PHP simply refuses oversized requests: it "will not process requests larger in size than the value for post_max_size."

The same page adds a scope note that most write-ups skip entirely:

"Note that post_max_size applies to every PHP request and not only uploads, so it may become important to address separately if a site processes a large amount of other data included with the request."

So post_max_size is not an "upload setting" that happens to also matter elsewhere. It is a site-wide request ceiling that uploads happen to run into.

Why raising only one does nothing

This is not a matter of interpretation — it is in WordPress core. The function behind the number your admin screen shows is wp_max_upload_size(), described in the developer reference as:

"Determines the maximum upload size allowed in php.ini."

And the function body:

function wp_max_upload_size() {
	$u_bytes = wp_convert_hr_to_bytes( ini_get( 'upload_max_filesize' ) );
	$p_bytes = wp_convert_hr_to_bytes( ini_get( 'post_max_size' ) );
	return apply_filters( 'upload_size_limit', min( $u_bytes, $p_bytes ), $u_bytes, $p_bytes );
}

Read it line by line and the whole confusion dissolves:

1. WordPress reads both directives, via ini_get().
2. It returns min() of the two — the smaller value wins.
3. The result then passes through an upload_size_limit filter, so the value core reports is min() after filtering.
4. The values come from php.ini, not from the WordPress database.

That min() is the entire answer to "which one wins." Set upload_max_filesize to 512M while post_max_size stays low, and WordPress reports the low number — because that is the smaller of the two. Raise post_max_size alone and nothing moves either, because upload_max_filesize is now the smaller one. The two have to move together, with post_max_size at or above upload_max_filesize.

What the admin screen is actually telling you

On the Media → Add New screen, the documentation says:

"You will also see a message displayed at the bottom of your view that indicates maximum upload size for files, as set by your hosting provider."

Note the attribution: as set by your hosting provider. That message is wp_max_upload_size() reporting a value it read from PHP — it is not a WordPress preference you can edit. Settings → Media has no file size field at all; the entire "Uploading Files" section of that screen documents one checkbox, for organizing uploads into month- and year-based folders.

WordPress's documentation gives no default numbers for either directive. Any "the WordPress default is 2 MB" claim you find elsewhere is not coming from the official docs, so treat your host's actual value as the only real one.

What to do when you hit the limit

The PHP Optimization page is blunt about who controls these values:

"Bear in mind that on shared hosting accounts, those limits are usually set on a server level and you may not be able to modify them or increase them above a certain value."

That reframes the problem. If you cannot raise the ceiling, the only lever left is the file itself — making it smaller before you upload it, no hosting ticket required:

If you want the controls rather than a preset, the video compressor exposes them; the rest are in all Clapr tools.

If you can edit PHP configuration, change both directives in the same pass and keep post_max_size greater than or equal to upload_max_filesize. The docs note only that "Some server environment may allow PHP configurations to be customized with other files like the .htaccess or .user.ini file" — they do not publish the directives to write there, so follow your host's instructions rather than a snippet from a forum.

Gotchas these two directives do not cover

Multisite adds a second, separate ceiling. The Network Admin settings screen documents an upload space limit — "Limit total size of files uploaded to [ 50 ] MB" — and a per-file "Max upload file size" whose "Default is [ 1500 ] KB." The documentation does not state how the network setting and the PHP directives combine, so check both when a Multisite upload fails.

Timeouts are a different axis. A large file can fit under both size limits and still die on the clock. Two directives are documented: max_execution_time, which "limits code execution, and not system library calls or MySQL queries, except on Windows, where it does"; and max_input_time, which is "usually used to limit the amount of time allowed to upload files." That second one is the upload-relevant one, and almost nobody mentions it. The matching error text is documented as "Maximum execution time of 30 seconds exceeded" or "Maximum execution time of 60 seconds exceeded."

Memory is a third axis. Core defines WP_MEMORY_LIMIT (documented default 40 MB, 64 MB on Multisite) for the front end and WP_MAX_MEMORY_LIMIT (documented default 256 MB) for the admin — and the docs say of the admin limit: "This is mainly required for media uploads."

None of this applies to WordPress.com. There you cannot edit php.ini; limits come from your plan, and the support docs say only that "You can reliably upload files up to 2 GB" — a reliability statement, not a published hard cap. More on that split in our limits guides.

FAQ

Which value does WordPress actually use, upload_max_filesize or post_max_size? The smaller of the two. Core's wp_max_upload_size() reads both from php.ini and returns min() of them, then passes that through the upload_size_limit filter.

Why did raising upload_max_filesize alone not change anything? Because post_max_size was then the smaller value, and min() picked it. Both have to be raised, and the docs require post_max_size to be greater than or equal to upload_max_filesize.

What are WordPress's default values for these directives? The official documentation states no default numbers for either one. It says only that the maximum upload size is "as set by your hosting provider" — so check the official documentation and your host's panel for the values in force on your site.

Does post_max_size affect anything besides uploads? Yes. The docs note it "applies to every PHP request and not only uploads," and flag it as something to address separately on sites that send a lot of other data with requests.

Can I change these on shared hosting? Often not. The docs warn that on shared hosting these limits "are usually set on a server level and you may not be able to modify them or increase them above a certain value."

Quotes from WordPress's Advanced Administration Handbook (PHP Optimization, Network Admin Settings), the developer reference for wp_max_upload_size(), and the Media Add New / Settings Media screens, checked 16 September 2026. Verify current wording against the official documentation before relying on it.