pyinstaller: error: unrecognized arguments (tested causes)

pyinstaller: error: unrecognized arguments is usually a single-dash -onefile, a second script placed after an option, or Windows ; syntax for --add-data. Use --onefile, put scripts first, and write --add-data "src:dest".

pyinstaller: error: unrecognized arguments means argparse found a word it could not place. Measured with PyInstaller 6.22.3 on Python 3.13.5 (Linux); the transcripts ran in order in one directory containing main.py, extra.py and data.txt, and are unedited.

1. The usual causes: single dash, extra scripts, Windows add-data syntax

Transcript:

$ pyinstaller main.py -onefile 2>&1 | tail -1
pyinstaller: error: unrecognized arguments: -onefile
$ pyinstaller --onefile main.py --hidden-import requests extra.py 2>&1 | tail -1
pyinstaller: error: unrecognized arguments: extra.py
$ pyinstaller --onefile --add-data 'data.txt;.' main.py 2>&1 | tail -1
pyinstaller: error: argument --add-data: Wrong syntax, should be --add-data=SOURCE:DEST
$ pyinstaller --noconfirm --log-level ERROR --onefile --add-data 'data.txt:.' main.py && ls dist
main

-onefile with one dash is not an option, so it is reported as an unrecognized argument: use --onefile or -F. Script names must come together: once an option sits between main.py and extra.py, the second script is left over and rejected. Put every script first, or better, pass only the entry script and let PyInstaller follow the imports. For --add-data PyInstaller 6 takes SOURCE:DEST on every platform; the old Windows form data.txt;. gives Wrong syntax, should be --add-data=SOURCE:DEST on Linux. Quote the value so your shell does not treat ; as a command separator.

2. Options removed in PyInstaller 6, abbreviations, and .spec files

Transcript:

$ pyinstaller --onefile --key secret main.py 2>&1 | tail -1
ERROR: Bytecode encryption was removed in PyInstaller v6.0. Please remove your --key=xxx argument. For the rationale and alternatives see https://github.com/pyinstaller/pyinstaller/pull/6999
$ pyinstaller --win-private-assemblies main.py 2>&1 | tail -1
ERROR: Support for collecting and processing WinSxS assemblies was removed in PyInstaller v6.0. Please remove your --win-private-assemblies argument.
$ pyinstaller --noconfirm --log-level ERROR --onefile --noconsol --nam app main.py && ls dist
app
main
$ pyinstaller --noconfirm main.spec --onefile 2>&1 | tail -3
ERROR: option(s) not allowed:
  --onedir/--onefile
makespec options not valid when a .spec file is given
$ pyinstaller --noconfirm --log-level ERROR main.spec && ls dist
app
main

--key (bytecode encryption) and --win-private-assemblies were removed in v6.0; PyInstaller now names the option and tells you to delete it, so old tutorials and build scripts are a common source of errors. Unambiguous prefixes are accepted: --noconsol and --nam app worked, so a typo can silently match a different option instead of failing. Finally, when you build from a .spec file, options such as --onefile, --name or --add-data are rejected with makespec options not valid when a .spec file is given: edit the spec instead, or rerun pyinstaller on the .py to regenerate it.

Related: pip error: externally-managed-environment, uv pip install -r requirements.txt.

If the built exe fails with ModuleNotFoundError, see PyInstaller: No module named.

Written with AI assistance. Measured on 2026-10-23 with PyInstaller 6.22.3 and CPython 3.13.5 on Linux. Each transcript was produced by running the commands verbatim in one directory. PlainHeaders is our extension; PyInstaller is free.