Skip to content
Get packs

Guide · Open source

How to use N_m3u8DL-CLI: download m3u8 streams from the command line

Updated · written with AI from the project's own documentation and checked against our catalogue data

N_m3u8DL-CLI is a free, open-source command-line downloader for m3u8 (HLS) and DASH streams. It saves a stream from a link or a local file as mp4 or ts. This guide explains what it is built on, how to get it, and how to run it with the options that matter most for custom headers, proxies, segment ranges and merging.

N_m3u8DL-CLInilaoda/N_m3u8DL-CLI · ★ 16.2k · MIT

Quick start

  1. 1Download the release. Go to the releases page linked in the README and download the Windows build. Install .NET Framework if your system does not have it.
  2. 2Install ffmpeg if needed. Only install ffmpeg if you plan to use the ffmpeg merge option. Otherwise you can use built-in binary merging.
  3. 3Open a terminal in the program folder. Run the tool from Command Prompt or PowerShell so you can pass options.
  4. 4Run a basic download. Pass the m3u8 URL and a --saveName value. Output is saved as mp4 or ts.
  5. 5Add headers or a proxy if required. Use --headers and --proxyAddress when the stream needs them.
  6. 6Set cleanup and merge options. Choose --enableDelAfterDone, --noMerge or --enableBinaryMerge to suit your workflow.

What N_m3u8DL-CLI is and whether it fits your system

N_m3u8DL-CLI is a command-line m3u8 downloader written in C#. It downloads m3u8 links or files and saves them as mp4 or ts, and it supports AES-128-CBC decryption, multi-threaded downloads, resuming, and custom HTTP headers.

The README states that this version is built on .NET Framework and is not cross-platform. It is aimed at Windows, and the project is now in a maintenance phase. The author points to N_m3u8DL-RE for Win/Linux/Mac users.

  • Good fit: Windows users who want a scriptable command-line m3u8 downloader.
  • Not a fit: Linux or macOS users, who should look at N_m3u8DL-RE instead.
  • Not supported: Youku and Balloon Cloud (气球云) video decryption, according to the README.

Install N_m3u8DL-CLI on Windows

The README links to a releases page for downloads and an actions page for automatic builds intended for testing. Download the release build from the releases page. The README lists .NET Framework as a prerequisite but does not state the exact version. ffmpeg is optional and only needed if you use the ffmpeg merge option.

The README also includes a clone command for the source code. Only use it if you want the source rather than a release build.

  • Prerequisite: .NET Framework (exact version not stated in the README).
  • Optional: ffmpeg, only for the ffmpeg merge option.
  • Releases: https://github.com/nilaoda/N_m3u8DL-CLI/releases
git clone https://github.com/nilaoda/N_m3u8DL-CLI.git

Run your first download

The basic syntax takes a URL, a JSON file or a local file as the first argument, followed by options. Use --saveName to set the output file name without the extension, and --workDir to choose the working folder.

The README's usage line is shown below. Replace the URL with your own m3u8 link.

  • Argument: URL, JSON or FILE as the input.
  • --saveName sets the output name, without the suffix.
  • --workDir sets the program's working directory.
N_m3u8DL-CLI <URL|JSON|FILE> [OPTIONS]

Add custom headers, a proxy and a download limit

Many streams require a Referer, cookie or other header. Use --headers with the format key:value and separate multiple keys with |. To send traffic through a proxy, use --proxyAddress with an HTTP or SOCKS5 address. If you do not want the program to use your system proxy, add --noProxy.

Use --maxThreads and --minThreads to set the thread range (defaults are 32 and 16). --retryCount (default 15) and --timeOut (default 10 seconds) control retries and timeouts. --maxSpeed limits download speed in KB/s.

  • --headers: key:value pairs, separated by |.
  • --proxyAddress: HTTP or SOCKS5, for example http://127.0.0.1:8080.
  • --noProxy: stop automatic use of the system proxy.
  • --maxSpeed: upper speed limit in KB/s.
N_m3u8DL-CLI "https://example.com/abc.m3u8" --saveName "abc" --headers "Referer:https://example.com|User-Agent:Mozilla/5.0" --proxyAddress http://127.0.0.1:8080

Download only part of a stream and handle decryption

For AES-128-CBC encrypted streams, the tool decrypts automatically. If you need to supply the key yourself, use --useKeyFile for a 16-byte key file, --useKeyBase64 for a Base64 key, and --useKeyIV for an IV in hex.

To download a section, use --downloadRange, which selects part of the segments or length of the video. The README does not give the exact range syntax, so check the user documentation before relying on it.

  • --useKeyFile: path to a 16-byte key file.
  • --useKeyBase64: key as a Base64 string.
  • --useKeyIV: IV as a hex string.
  • --downloadRange: download only part of the segments or length.

Merge output into mp4 or audio only

By default the tool merges the downloaded parts after finishing. You can merge with built-in binary merging (--enableBinaryMerge) or with ffmpeg. Use --noMerge to turn off automatic merging and keep the parts. --enableDelAfterDone removes the temporary folder after a download completes.

--enableAudioOnly packages only the audio track when merging. --enableMuxFastStart turns on the FastStart option for mp4 files.

  • --enableBinaryMerge: merge segments with built-in binary merging.
  • --noMerge: skip automatic merging.
  • --enableDelAfterDone: delete the temporary folder when done.
  • --enableAudioOnly: keep only the audio track.

What people use it for

  • Download an m3u8 stream that requires a Referer or other custom HTTP header.
  • Fetch a stream through a local HTTP or SOCKS5 proxy.
  • Save a stream to a Windows folder with a fixed file name, for use in a script.
  • Download a section of a stream with --downloadRange.
  • Extract only the audio track from a stream with --enableAudioOnly.

Frequently asked questions

Is N_m3u8DL-CLI free?

Yes. The project is open source under the MIT licence, according to the README. You can download the release builds from the releases page.

Does N_m3u8DL-CLI work on Mac or Linux?

The README says this version is based on .NET Framework and is not cross-platform. For Win/Linux/Mac, the author recommends N_m3u8DL-RE.

What do I need to install before using it?

The README lists .NET Framework as a prerequisite, without giving the exact version. ffmpeg is optional and only required for the ffmpeg merge option.

Can it decrypt Youku or Balloon Cloud videos?

No. The README explicitly says Youku and Balloon Cloud (气球云) video decryption is not supported.

Is N_m3u8DL-CLI still being developed?

The README says the project has entered a maintenance phase, so new features are not expected here. New features are being added to N_m3u8DL-RE.

How does it compare with yt-dlp or ffmpeg?

The source describes N_m3u8DL-CLI as a dedicated m3u8 downloader with options for headers, proxies and segment ranges. It does not compare it with yt-dlp or ffmpeg, so check those projects' documentation for their own feature sets. ffmpeg is used here only as an optional merge step.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

N_m3u8DL-CLI suits Windows users who want a scriptable m3u8 downloader with custom headers, proxies and segment selection. If you use Linux or macOS, or need new features, choose N_m3u8DL-RE, which the author describes as its successor.

Install options & downloads