Skip to main content
mpv accepts options on the command line, in configuration files, and at runtime through the scripting and IPC APIs. This page explains the general option system before diving into specific option groups.

​
Command-line syntax

Arguments starting with - are interpreted as options; everything else is treated as a filename or URL. 
mpv [options] [file|URL|-]
Most options require a value: 
mpv --option=value file.mkv
The canonical form is --option=value (double dash, equals sign). The legacy forms -option value and -option=value are accepted for compatibility but should be avoided.

​
Flag options

Flag (boolean) options have a --no- counterpart and do not require a value: 
mpv --fullscreen file.mkv       # enable fullscreen
mpv --no-fullscreen file.mkv    # disable fullscreen
mpv --fs=yes file.mkv           # same as --fullscreen
mpv --fs=no file.mkv            # same as --no-fullscreen

​
Getting help for an option

mpv --option=help    # list valid values for choice options
mpv --list-options   # list all available options with types and defaults

​
Option types

TypeDescriptionExample
flagBoolean yes/no--fullscreen, --no-audio
stringArbitrary text--title="My Window"
integerWhole number--osd-level=2
floatDecimal number--speed=1.5
choiceOne of a fixed set of strings--hr-seek=yes
colorr/g/b or #RRGGBB--osd-color='#FFFFFF'
geometryWindow placement string--geometry=1280x720
bytesizeSize with unit suffix--demuxer-max-bytes=512MiB
time[[hh:]mm:]ss[.ms]--start=01:30:00
object listComplex filter chains--vf=scale=1920:1080

​
List options

Several options accept comma-separated lists. These support action suffixes to modify lists incrementally rather than replacing them entirely.

​
String list and path list options

# Set the whole list
mpv --display-tags=Title,Artist,Album file.flac

# Append a single item (no escaping needed)
mpv --display-tags-append=Comment file.flac

# Prepend items
mpv --sub-files-pre=/path/to/subs.srt file.mkv

# Remove an item
mpv --display-tags-remove=Comment file.flac

# Clear the list
mpv --display-tags-clr file.flac
SuffixEffect
-setReplace the entire list
-appendAppend one item (no escape interpretation)
-addAppend one or more items
-prePrepend one or more items
-clrClear the list
-delDelete matching items
-removeDelete one item (no escape interpretation)
-toggleAppend, or remove if already present
Some options store key/value pairs (like --script-opts). Keys are unique — setting an existing key overwrites it.
SuffixEffect
-setReplace the entire map
-appendAppend one key=value pair
-addAppend one or more pairs
-clrClear the map
-delDelete by key
-removeDelete one key (no escape interpretation)

​
Example: building a sub-file list incrementally

mpv --sub-files-append=/path/to/en.srt --sub-files-append=/path/to/commentary.srt file.mkv

​
Configuration files

You can store options in ~/.config/mpv/mpv.conf. The syntax mirrors the command line but without leading --: 
# ~/.config/mpv/mpv.conf

# Don't allow new windows larger than the screen
autofit-larger=100%x100%

# Hardware decoding when available
hwdec=auto

# OSD message on playback start
osd-playing-msg=File: ${filename}

# Default subtitle language
slang=en,eng
Options that are flags can use yes explicitly or just the bare name (which implies yes): 
fullscreen=yes
# same as:
fullscreen

​
Profiles

Profiles group multiple options under a name so they can be applied together. 
# ~/.config/mpv/mpv.conf

# top-level options (always active)
vo=gpu

[big-cache]
cache=yes
demuxer-max-bytes=512MiB
demuxer-readahead-secs=20

[network]
profile-desc="profile for network playback"
force-window=immediate
profile=big-cache
Apply a profile on the command line: 
mpv --profile=network https://example.com/stream.m3u8
List defined profiles: 
mpv --profile=help
Inspect a specific profile: 
mpv --show-profile=network

​
Built-in profiles

mpv ships several built-in profiles you can apply directly:

fast

Uses lower-quality but faster scalers. Sets scale=bilinear, dscale=bilinear, and disables some processing steps.

high-quality

Enables the ewa_lanczossharp scaler and other quality-enhancing settings at the cost of more GPU usage.

sw-fast

Optimizes for software rendering performance, disabling GPU-intensive features.
mpv --profile=high-quality file.mkv
mpv --profile=fast file.mkv

​
Conditional auto profiles

Profiles with profile-cond are applied automatically when a Lua expression evaluates to true: 
[hd-video]
profile-desc=Apply settings for HD video
profile-cond=width >= 1280
deband=yes

[youtube-brighter]
profile-cond=path:find('youtu%.?be')
gamma=20

[fullscreen-rotate]
profile-cond=fullscreen
profile-restore=copy
vf-add=rotate=PI/2
Conditions are re-evaluated whenever a referenced property changes. Avoid using frequently-changing properties like playback-time in conditions, as this re-evaluates on every frame.

​
Options vs. properties

Options and properties are related but distinct:
  • Options are set on the command line or in config files. They define the initial state.
  • Properties are the runtime state of the player, readable and writable via input commands, scripts, and IPC.
Most options have a corresponding property of the same name. You can change a property at runtime: 
# In the mpv console (` key) or input.conf:
set speed 2.0
cycle pause
add volume 5
Outside of playback, reading a property returns the option value. During playback, it returns the effective runtime value (which may differ from the option if mpv chose a different default).

​
Getting help

mpv --list-options          # all options, types, and defaults
mpv --list-properties       # all runtime properties
mpv --h=osd                 # options containing "osd" in their name
mpv --show-profile=fast     # contents of the "fast" built-in profile

Build docs developers (and LLMs) love

Get started for freeTalk to us