Shotcut exports from the command line by handing your project to melt, the same background engine the GUI uses. The User Guide puts it plainly: "It is fairly easy to run an export on the command line because Shotcut essentially does the same thing."
The part that trips people up is not the command. It is the assumption that comes with it — that because the encoding is done by FFmpeg underneath, you can paste FFmpeg flags in and they will work. Shotcut's documentation explicitly says otherwise, and that one paragraph is worth more than any command you will copy today.
The command
The User Guide gives this example verbatim:
LC_ALL=C melt project.mlt -consumer avformat:export.mp4That is the whole thing: an environment variable, the melt binary, your saved project file, and an output consumer with a filename attached.
What each part does
LC_ALL=C — the guide explains this as a locale guard: "LC_ALL=C sets that environment variable to mitigate problems with numeric strings in some locales." Decimal separators differ between locales, and encoding parameters are full of decimals. Leave it in.
project.mlt — your saved Shotcut project, not a video file. The Export panel exists in the first place "because File > Save saves a project file", as the guide notes. The command line is doing the same conversion step the Export panel does.
-consumer avformat:export.mp4 — the output side, with the destination filename after the colon. What you get from the bare command, again in the guide's words: "That command line generates a H.264/AAC MP4 using software encoder x264 with melt & FFmpeg's default encoding options."
Two things follow from that sentence. It is a software x264 encode, not your GPU — for what hardware encoding does and does not cover, see which codecs Shotcut's hardware encoders support. And it uses defaults, not your Export panel settings, because nothing in that command line ever read them.
The warning that matters more than the command
Here is the passage most third-party tutorials skip. From the same section of the User Guide:
"Please keep in mind that Shotcut is not a ffmpeg command line front end except in the rare cases of Properties > Convert and Reverse and proxy media generation. Thus, there are many things you cannot copy from ffmpeg examples are possible here. Only options from FFmpeg that affect the encoder or muxer."
And, restating the scope:
"Melt only accepts the encoder and muxer options here, but only some of ffmpeg's options are for the encoder and muxer."
So the mental model "Shotcut's Advanced export is an FFmpeg command builder" is wrong by the documentation's own account, with three named exceptions: Properties > Convert, Reverse, and proxy media generation.
There is also a syntax difference that will bite you within the first minute:
"Notice that each option is not preceded by one or two dashes."
Write crf=23-style bare names, not -crf. An FFmpeg snippet pasted in with its dashes intact is not a "wrong value" error — it is not the right shape of input at all.
Overriding parameters the supported way
Inside the GUI, the Advanced tab is where extra parameters go, and the guide describes the precedence rules:
"Most essential parameters are written by the presets and various form fields of Export > Advanced but you can override them here (must use the correct name, of course). Some parameters are appended to the generated ones. For example, you can supply a x265-params , and the Codec tab will prepend values needed for rate control. Prepending lets you specify overrides."
Read that "prepend" detail carefully: because Shotcut's rate-control values go in first, your values come later and win. That is the intended override mechanism.
The guide attaches a blunt disclaimer to the whole Advanced mode: "by clicking Advanced you should understand that Shotcut expects you to be advanced and know what you are doing. There are simply too many combinations of settings and options that Shotcut's advanced export mode lets you create invalid combinations and does not protect you from yourself." One practical note from the same section — Advanced turns itself off again on the next restart unless you pin it with the checkbox next to Advanced.
Try it right here
Runs in your browser. Your file is not uploaded anywhere.
If the reason you reached for the command line was batch-shrinking finished exports rather than driving the editor, the compressor above does that in a browser tab with no install. Compress video is the same job from the tool page.
Let Shotcut write the command for you
You do not have to compose the parameter list by hand. Two documented routes:
From the application log. Run an export in the UI, then open View > Application > Log... and scroll to the end. The guide says "You will see the command line printed; however, the file name is fully encoded to workaround potential character set problems." Expect to replace that encoded filename with a readable one.
From a stopped job's XML. The guide's step list for this ends with, verbatim: "5. Right-click the new job in Jobs and choose Stop", "6. Right-click the job and choose View XML", "9. At the command line run LC_ALL=C melt job.xml". Starting the export and immediately stopping it makes Shotcut generate the full job description without spending time encoding. The Jobs panel's View XML entry is described as showing "the MLT XML code that was sent to the background "Melt" engine to process the job" — that is exactly the file you then feed back to melt.
Inside that XML you will find the output line Shotcut wrote, which the guide shows as <consumer mlt_service="avformat" movflags="+faststart"... />. Treat the movflags value there as part of that example, not as documented default UI behaviour.
Three melt-adjacent switches are listed on Shotcut's Command Line Options page: --gpu ("Use GPU processing."), --appdata <directory> ("The directory for app configuration and data."), and --noupgrade. Separately, a configuration key controls "the priority of background melt and ffmpeg jobs such as export and proxy: low (default) or normal".
Troubleshooting
The export fails or produces an unplayable file. The guide lists the common pitfalls as "Choosing a codec not supported by the selected container Enabling hardware encoding with unsupported formats Mixing incompatible pixel formats or profiles", and says these can "Cause export failure Produce unplayable files Result in silent audio or missing video". Silent audio after a hand-edited parameter list usually means an invalid combination, not a bug.
A GUI job fails and you want the real error. Right-click the failed job and use View Log, described as "Essential for diagnosing "Failed" exports."
It hangs partway. Shotcut's FAQ gives one procedure: stop the job from the Jobs panel, retry with "Export > Video > Parallel processing disabled (unchecked)", and if it still fails, note the percentage reached and "apply the percentage to your project duration to find the rough time of where it seems to be having trouble." Then look at what is on the timeline there.
Odd characters in the path. The release notes record filename-related export fixes — "Fixed export with '&' in the file path or name." in Release 25.10.31, and a special-characters-on-Windows fix in Release 25.12.30. Those are records of fixes in specific versions, not a statement about current behaviour, but a plain ASCII path is still the cheapest variable to remove while debugging.
FAQ
Can I use ffmpeg flags in Shotcut's Advanced export? Only the subset that affects the encoder or muxer. The guide states Shotcut "is not a ffmpeg command line front end" apart from Convert, Reverse and proxy generation, and that melt "only accepts the encoder and muxer options here". Options are also written without leading dashes.
Where do I find the exact melt command for my project?
Export once in the UI and read the end of View > Application > Log..., or start a job, stop it, and use View XML from the Jobs panel, then run LC_ALL=C melt job.xml.
Do I need LC_ALL=C? The guide includes it in its own example and explains it mitigates problems with numeric strings in some locales. Keep it.
Does the command line export use my GPU?
The documented one-liner is described as producing an H.264/AAC MP4 with the software encoder x264. A --gpu switch exists on the Command Line Options page; for the export-side hardware encoder question, check the official documentation for your specific setup.
What quality settings does the bare command use? FFmpeg's defaults, per the guide's wording. The official pages we could check give no CRF or bitrate figures for Shotcut's presets, so read the numbers off a real export's XML rather than guessing at an equivalent.
More command-line recipes live in the ffmpeg guides, and every browser-based converter and compressor is listed on the tools page. Quotes above are from Shotcut's official User Guide, FAQ, Command Line Options and release notes, checked 21 September 2026.
