WordPress's Video block can be transformed into a "Gif variation" — but nowhere in the official documentation does it say that this produces a .gif file. That gap is why so many "convert video to GIF in WordPress" guides leave readers clicking Transform and then wondering why the Media Library still shows a video.
This guide separates the two things people mean by that search. First, what the block editor documents about the Gif variation, quoted directly. Second, the route that ends with an actual GIF file you can upload, reuse, or send somewhere that has nothing to do with WordPress.
Before you start
- A video clip on disk. Short is better here, purely for size reasons — every route below ends at an upload, and uploads are where WordPress limits bite.
- Know which WordPress you are on. Self-hosted sites take their upload limit from PHP; WordPress.com takes it from your plan. The two have separate documentation and separate rules, and mixing them up is the single most common error in this topic.
- Check the accepted file types list for your setup. WordPress.com states plainly: "WordPress.com restricts uploads to the file types listed on this page. Restricting file types protects your site from unsafe files." For self-hosted sites, the allowed extensions come from core's own MIME map — see WordPress supported video file types.
What the Gif variation actually is
The official Video block documentation says exactly two things about it:
"The Video block can easily be transformed into a Gif variation of the Video block using the Transform to variation button."
"Click on the Transform button to convert the Video block to a Gif variation, Group, Cover, Media & Text, Columns, Details, or File block."
Read the second sentence carefully. Gif variation is listed in the same breath as Group, Cover, Media & Text, Columns, Details, and File. Those are all blocks. What the documentation describes is a block-level operation — the editor swaps one block for another — and it says nothing about encoding, output format, or any file being produced.
The block editor behaves the same way elsewhere, and the docs confirm it: "If you insert a URL from a supported block type, such as YouTube, the Video block will automatically transform into a YouTube embed block." Nothing was converted there either. A block became a different block.
So if you need a .gif file, the Transform button is not the step that creates one. Beyond the two sentences above, WordPress's documentation does not describe what the Gif variation changes — for anything more specific, check the official documentation rather than a blog post that guessed.
Step 1: Transform the block, if that is what you wanted
If a Video block that presents itself differently is genuinely all you need, this part is short.
- Select the Video block in the editor.
- Open the Transform to variation button, which the documentation names as the control for this.
- Choose Gif variation from the list.
That is the whole documented procedure. Note what you still have afterwards: a Video block, with a video file behind it. The Video block's own performance settings still matter, and the docs are blunt about the cost of the wrong one. On Preload: "Auto – The entire video file is downloaded, regardless of whether the visitor clicks the Play button or not. This makes the biggest impact on your page or post's load speed, especially with larger video files." And: "None – Nothing about the video file is downloaded automatically. The download of the video file only begins when your visitor clicks the Play button. This is the fastest setting."
Step 2: Make an actual GIF file
For a real .gif, the conversion has to happen before WordPress sees the file. WordPress.com's own troubleshooting page endorses exactly this order of operations for anything it cannot take as-is: "If you have images and other files in unsupported formats that you want to use, then you should convert them to a valid file type before uploading. You can do this with editing software or a free online converter."
Try it right here
Runs in your browser. Your file is not uploaded anywhere.
This runs inside your browser tab — the clip is read from disk, converted locally, and handed back to you, so nothing is uploaded to a third-party server on the way to fixing an upload problem. Trim to the few seconds you actually want before converting, because the file you end up with is the one that has to clear the limits in the next step.
Step 3: Upload it and place it
Upload the finished .gif to your Media Library, the same place WordPress.com points users after a conversion: "a tool like HandBrake can be used to convert it before you upload it to the Media Library."
This is also the moment the limits show up, and they differ by setup:
| Where your site runs | What sets the ceiling |
|---|---|
| Self-hosted | PHP, "as set by your hosting provider" |
| Self-hosted Multisite | A network setting, default "1500 KB" |
| WordPress.com | Plan storage, plus a "reliably upload" ceiling |
On self-hosted WordPress there is no size setting in WordPress itself. The Media screen documentation says the number you see is "maximum upload size for files, as set by your hosting provider", and core's wp_max_upload_size() is described as "Determines the maximum upload size allowed in php.ini" — it returns the smaller of the upload_max_filesize and post_max_size directives. Details in maximum upload file size in WordPress.
On Multisite there is a second, separate gate: the Network Admin settings screen documents a Max upload file size whose "Default is [ 1500 ] KB." — see Multisite max upload file size.
On WordPress.com, the accepted file types page says "You can reliably upload files up to 2 GB to your WordPress.com site", and adds that "Your site's available storage also limits file size. You cannot upload a file that is larger than the storage space remaining on your site."
Common mistakes
- Expecting a downloadable GIF after clicking Transform. The documentation never claims one is produced. Convert first, then upload.
- Assuming a rejected file was too big. WordPress.com's upload error list is explicit about the message "This file cannot be processed by the web server." — of it, the page says: "The file type is not supported. This message is not about the file's size."
- Testing on Multisite without checking the network setting. A file that uploads fine on a single-site install can be blocked by the 1500 KB network default.
- Routing a GIF through VideoPress. VideoPress "automatically converts it to MP4 format using H.264 video and AAC audio compression" — the opposite direction from where you are heading.
- Uploading the full-length clip. Trim before converting, not after.
FAQ
Does the WordPress Gif block convert my video to a GIF file?
The documentation does not say so. It says only that the Video block "can easily be transformed into a Gif variation of the Video block", and lists that variation alongside block transforms like Group, Cover and Columns. No official page describes a .gif file being produced.
How do I get a real GIF onto a WordPress post then?
Convert the clip to .gif before uploading with a converter such as MP4 to GIF, then upload the result to your Media Library. WordPress.com's own guidance for unsupported formats is to "convert them to a valid file type before uploading", with "editing software or a free online converter".
Why was my GIF rejected on upload? Check the message rather than assuming size. WordPress.com's error list separates a file-type refusal from a size problem, and self-hosted installs show a type error too: "Sorry, this file type is not supported here." On Multisite, an unsupported type fails with "Sorry, this file type is not permitted for security reasons".
What size can my GIF be?
It depends on where the site runs, and WordPress publishes no universal number. Self-hosted limits come from php.ini via the hosting provider; Multisite adds a network default of 1500 KB; WordPress.com documents reliable uploads "up to 2 GB" bounded by your plan's remaining storage.
Is keeping it as a video better than a GIF? Often, yes — a Video block with Preload set to None downloads nothing until the visitor presses Play, which the docs call "the fastest setting". A GIF starts downloading with the page. Use a GIF when you need a file that works outside your site.
More step-by-step WordPress media guides live in the how-to hub, and the rest of the browser-side converters are listed under all Clapr tools.
Quotations from WordPress's official block editor and Advanced Administration documentation and from WordPress.com's help centre, checked 16 September 2026. Where the official pages are silent — including on what the Gif variation changes — this article says so rather than filling the gap.
