Convert Videos

This tool allows bulk conversion of videos using ffmpeg, including with hardware acceleration.

By default it will append the codec name to the file, e.g. Best Movie Ever.avi -> Best Movie Ever - x265.mkv. This can be optionally overridden using the --in-place flag.

Videos are only converted if they do not already match the desired codec, allowing you to process a folder of mixed format files and only convert the ones you desire. This can optionally be overridden.

Usage

Run directly without installing using uvx:

# Convert all videos in a directory to HEVC (x265)
uvx convert-videos /path/to/videos

# Run in-place with hardware acceleration (e.g. AMD, Nvidia, Intel, or auto-detect)
uvx convert-videos --in-place --encoder auto-detect -q 22 /path/to/videos

# Keep only English audio and subtitles
uvx convert-videos --audio-language eng --subtitle-language eng /path/to/videos

# Perform a dry-run with verbose output
uvx convert-videos --dry-run -v /path/to/videos

You can also install it as a persistent tool:

uv tool install convert-videos
# or
pip install convert-videos

Options

Usage: convert-videos [OPTIONS] DIRECTORIES...

Options:
  --version                       Show the version and exit.
  -i, --in-place                  Replace the original files instead of
                                  appending the new codec name
  -f, --force                     Force conversion even if the format of the
                                  file already matches the desired format
  --video-codec TEXT              A target video codec. Supported codecs:
                                  HEVC, AVC  [default: HEVC]
  -q, --quality INTEGER           The quantizer quality level to use.
                                  [default: 24]
  -p, --preset TEXT               FFmpeg preset to use.  [default: medium]
  -w, --width INTEGER             Specify a new width to enable resizing of
                                  the video
  --extra-input-args TEXT         Specify any extra arguments you would like
                                  to pass to FFMpeg input here
  --extra-output-args TEXT        Specify any extra arguments you would like
                                  to pass to FFMpeg output here
  --audio-codec TEXT              A target audio codec  [default: AAC]
  --audio-channels INTEGER        The number of channels to mux sound in to
                                  [default: 2]
  --audio-bitrate INTEGER         The bitrate to use for the audio codec
                                  [default: 160]
  --temp-dir TEXT                 Specify a temporary directory to use during
                                  conversions instead of the system default
  -v, --verbose                   Enable verbose log output
  --container TEXT                Specify a video container to convert the
                                  videos in to  [default: mkv]
  --dry-run                       Do not make actual changes
  --encoder [auto-detect|software|nvidia|intel|amd]
                                  Optionally use a hardware encoder to speed
                                  things up.  [default: auto-detect]
  --audio-language TEXT           Only include audio streams in this language
  --subtitle-language TEXT        Only include subtitle streams in this
                                  language
  --minimum-size-per-hour INTEGER
                                  Skip videos smaller than this threshold (in
                                  MB per hour of duration).
  -h, --help                      Show this message and exit.

Autocomplete

To enable auto-completion:

zsh Add the below to ~/.zshrc eval "$(_CONVERT_VIDEOS_COMPLETE=zsh_source convert-videos)"

bash Add the below to ~/.bashrc eval "$(_CONVERT_VIDEOS_COMPLETE=bash_source convert-videos)"

fish Add the following to ~/.config/fish/completions/convert-videos.fish eval (env _CONVERT_VIDEOS_COMPLETE=fish_source convert-videos)

File output

Container

The default output container is mkv format. This can be changed with the --container flag to anything that is supported by FFMPEG and the chosen video and audio codecs

Video output

Default settings is HEVC/x265 at quality of 23

Codecs

Currently only HEVC (x265) and AVC (h264) are supported for video codecs.

Resizing

Videos can be resized automatically by providing a width. Height is automatically calculated to ensure that the aspect ratio is maintained.

Hardware Acceleration

Hardware acceleration is supported on AMD, nVidia, and Intel devices.

Caveats for AMD:

Conversions use VA-API with CQP (Constant Quantization Parameter) mode for the quality setting.

Caveats for nVidia:

Conversions use constqp mode for the quality setting instead of CRF, as nvenc does not support CRF.
b-frames are not currently supported; nvenc itself supports them on 20xx+ series graphics cards.

Caveats for Intel:

Conversions use global_quality mode as CRF isn't supported on Intel hardware. ICQ and LA-ICQ are apparently better, but only supported on Windows.
Look-ahead is only supported on x264 (not HEVC).
There is a bug (current as of 2023-05) where all videos converted with Intel's QSV with FFMPEG have a single I-frame at the start and no more; so currently this is being worked around by enforcing a maximum time between I-frames which creates usable videos.
10-bit HEVC videos often cause issues with the Intel decoder.

Audio output

Default settings is 160kbps 2 channel AAC.

All audio streams will be included by default unless a language filter is specified with --audio-language.

Subtitles

All subtitles will be copied from the source if they exist unless a language filter is specified with --subtitle-language.

Skipping Already-Compressed Videos

Use --minimum-size-per-hour <MB> to skip files that are already small enough to not warrant re-encoding:

# Skip any video smaller than 500 MB per hour of playtime (e.g. a 2-hour movie under 1 GB is skipped)
uvx convert-videos --minimum-size-per-hour 500 /path/to/videos

Metadata

Release files for convert_videos 2.11.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for convert_videos 2.11.1
File	Size	Uploaded
convert_videos-2.11.1.tar.gz	32.2 kB	Oct 5, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for convert_videos 2.11.1
File	Interpreter	ABI	Platform	Reset
convert_videos-2.11.1-py3-none-any.whl 13.8 kB Oct 5, 2026	Python 3	none	any	Details

Total release size: 46.1 kB

Release files / convert_videos-2.11.1.tar.gz

Download URL	convert_videos-2.11.1.tar.gz
Size	32.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`ec9d9065230a82782570674ad8ebe9cf27689d5fb589e6df7323cece7ae99aa9`
BLAKE2b-256 checksum How to use checksums	`f4ca6e928cf4a490f0408b0820d745a94194264a54058f3982439e8db0ec1e89`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`

Release files / convert_videos-2.11.1-py3-none-any.whl

Download URL	convert_videos-2.11.1-py3-none-any.whl
Size	13.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`d71e1e51e4c71b4c993681364d5787b547e2df40066f3dc19646785a12999078`
BLAKE2b-256 checksum How to use checksums	`9c00c92a803de74036ab2c939734331784e06ba45eec3ad9ab181f0d4fdd06ec`
Upload date	Oct 5, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`uv/0.12.23 {"installer":{"name":"uv","version":"0.12.23","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}`