Play Video from the Raspberry Pi Command Line with OMXPlayer

Learn how to play local video files from the Raspberry Pi command line with legacy OMXPlayer, including full-screen playback, HDMI audio, keyboard controls, and troubleshooting.

OMXPlayer is a command-line media player created for Raspberry Pi. It was commonly included with historical Raspbian installations and used the Raspberry Pi GPU (Graphics Processing Unit) to accelerate video playback. This made it possible to play local video without launching the graphical desktop.

Raspbian is the former name for the Debian-based operating system used on Raspberry Pi. It is now generally called Raspberry Pi OS. OMXPlayer is legacy software, so it may not be installed or supported on a current Raspberry Pi OS release. This lesson explains the traditional OMXPlayer workflow and shows how to check whether it is available.

Compatibility note: If omxplayer is unavailable, check the documentation for your installed Raspberry Pi OS release and use a supported alternative such as VLC or mpv.

Prerequisites

A Raspberry Pi running Raspbian or a Raspberry Pi OS release that provides OMXPlayer.
Basic familiarity with a Raspberry Pi terminal and Linux commands.
A local video file, or the historical sample file described below.
A display connected to the Raspberry Pi, preferably through HDMI.
For sound, a television, monitor, or other audio device connected through HDMI, or suitable analog audio hardware.

Playback can be started from a terminal inside the desktop, or from a Raspberry Pi configured to boot directly to the console. Interactive controls require a keyboard and a terminal session that receives the keyboard input.

Check whether OMXPlayer is installed

Use which to find the executable:

which omxplayer

If the command prints a path, OMXPlayer is available through the current command search path. If it prints nothing or reports that the command cannot be found, OMXPlayer is probably not installed or is not supported by that operating-system release.

Play a local video file

The general command structure is:

omxplayer /path/to/video-file

A path identifies a file or directory in the filesystem. An absolute path starts at the root directory, represented by /, and describes the complete location of a file. For example:

omxplayer /home/pi/Videos/movie.mp4

A relative path is interpreted from the terminal's current directory. If the video is in a directory named Videos below the current directory, you could use:

omxplayer Videos/movie.mp4

OMXPlayer normally opens the video in full-screen playback. Full-screen playback means that the video occupies the display instead of appearing in a desktop window.

Shells treat spaces as separators between arguments. Put quotation marks around a filename or path containing spaces:

omxplayer "/home/pi/Videos/my video.mp4"

You can also escape each space with a backslash, but quoting the complete path is usually easier to read.

Purpose	Command	Explanation
Play a local file	`omxplayer /path/to/video-file`	Starts full-screen playback using the supplied path.
Play with HDMI audio	`omxplayer -o hdmi /path/to/video-file`	Sends sound through the HDMI connection.
Play a file whose path contains spaces	`omxplayer -o hdmi "/home/pi/Videos/my video.mp4"`	Quotes the complete path so the shell passes it as one argument.

Play the included H.264 sample video

Historical Raspberry Pi firmware source trees included an H.264 demonstration video in the hello_pi example files. H.264 is a widely used video compression format. On installations that contain this sample, its path is:

/opt/vc/src/hello_pi/hello_video/test.h264

Start it with:

omxplayer /opt/vc/src/hello_pi/hello_video/test.h264

The sample is useful for testing whether the traditional player can open a known local H.264 file. Its presence depends on the operating-system image and installed packages; it is not guaranteed to exist on every Raspberry Pi system.

Check for the file before trying to play it:

ls -l /opt/vc/src/hello_pi/hello_video/test.h264

If the command reports that the file does not exist, use another local video file and provide its correct path.

Send audio through HDMI

HDMI is a digital display connection that can carry both video and audio. A Raspberry Pi may display video through HDMI while sending sound somewhere else unless the audio output is selected explicitly.

Use the -o hdmi option to direct OMXPlayer audio to the connected television or monitor:

omxplayer -o hdmi /opt/vc/src/hello_pi/hello_video/test.h264

The same option works with a personal video:

omxplayer -o hdmi "/home/pi/Videos/my video.mp4"

On versions that support it, the local or analog output option is written as -o local. Use it when sound should go to the Raspberry Pi's analog headphone output rather than HDMI.

Output option	Destination	When to use it
`-o hdmi`	HDMI display or television	Use when the display or television should provide the audio.
`-o local`, where supported	Local analog or headphone output	Use when audio should be sent to the analog output instead of HDMI.

Keyboard playback controls

OMXPlayer reads controls from the terminal session that launched it. Click or return focus to that terminal before pressing keys. The exact controls can vary between OMXPlayer versions, especially subtitle controls.

Key or key group	Action	Notes
`Space`	Pause or resume	Press again to continue playback.
`q`	Quit playback	Ends playback and returns to the shell prompt.
Left arrow	Seek backward	Moves toward an earlier position in the video.
Right arrow	Seek forward	Moves toward a later position in the video.
`-` or the supported decrease-volume key	Decrease volume	Key behavior can depend on the installed build.
`+` or the supported increase-volume key	Increase volume	Use the key shown by the installed version's help output if needed.
`s`, if supported	Toggle subtitles	Only works when subtitle data is available and supported.
`d`, if supported	Change subtitle delay	Availability and exact behavior depend on the installed player version.

These controls affect the running player; they are not commands entered at a normal shell prompt. If playback is not responding, check that the terminal has focus and that the keyboard is connected to the session running OMXPlayer.

Command-line-only playback

A command-line interface is a text-based environment where programs are started by entering commands. OMXPlayer can be used entirely from this environment, so a graphical desktop is not required.

Connect the Raspberry Pi to a display through HDMI.
Connect a keyboard directly to the Raspberry Pi, or make sure the terminal session can receive keyboard input.
Boot to a terminal or open a terminal from the desktop.
Run an OMXPlayer command with the correct video path.
Use the keyboard controls while the player is running.

For an interactive test, a directly connected display and keyboard remove complications caused by remote terminals or sessions that do not pass local key presses to the player. Console boot behavior can be adjusted through the system's boot options.

Troubleshooting

“omxplayer: command not found”

This usually means that the player is not installed, is not in the command search path, or is not provided by the current Raspberry Pi OS release.

Run which omxplayer.
Check the documentation for the installed operating system.
Use a currently supported player, such as VLC or mpv, when OMXPlayer is unavailable.

The sample video cannot be opened

The sample may not be included in the installed image or package set, or the path may have been entered incorrectly. Verify it with:

ls -l /opt/vc/src/hello_pi/hello_video/test.h264

If it is absent, test with another local H.264-compatible video and use its complete path.

Video appears but the television has no sound

Run the player with -o hdmi. Then check that the television or monitor is not muted, the HDMI cable is connected correctly, and the selected display input provides audio. Some monitors accept HDMI video but do not contain speakers.

Playback is poor or the file does not play

Possible causes include an unsupported codec or container, a damaged file, or a mismatch between the old player and the current hardware or software. Test the supplied H.264 sample when available, then try a known-compatible H.264 file. On newer systems, use a supported media player instead.

Keyboard controls do nothing

Return focus to the terminal that launched OMXPlayer. A remote or background session may not receive keyboard input. For initial testing, use a directly connected keyboard and display.

Compatibility and migration

OMXPlayer depended on Raspberry Pi multimedia components that are no longer part of every current Raspberry Pi OS installation. It should therefore be treated as legacy software rather than a universal command for all Raspberry Pi systems.

The historical workflow remains:

omxplayer -o hdmi /path/to/video-file

When that command is unavailable, follow the media-player guidance for the installed Raspberry Pi OS release and migrate to a supported command-line-capable player such as VLC or mpv. The file path, audio-device configuration, and keyboard controls may differ between players.

Quick reference

# Check for OMXPlayer
which omxplayer

# Play a local video
omxplayer /path/to/video-file

# Play with HDMI audio
omxplayer -o hdmi /path/to/video-file

# Play the historical H.264 sample, if present
omxplayer /opt/vc/src/hello_pi/hello_video/test.h264

# Play the sample with HDMI audio
omxplayer -o hdmi /opt/vc/src/hello_pi/hello_video/test.h264

Exam-relevant points: OMXPlayer is a legacy command-line media player for Raspberry Pi; it commonly used GPU hardware acceleration; -o hdmi selects HDMI audio; absolute paths begin with /; quoted paths preserve spaces; and current Raspberry Pi OS releases may require VLC, mpv, or another supported alternative.

For related command-line skills, see useful terminal commands, playing audio on Raspberry Pi, and Raspberry Pi boot options.