{"record":{"id":"40230a07a63bf6e0","repo":"ArchiveBox/ArchiveBox","slug":"x-your-system-is-running-python3-scripts-with-a","errorCode":null,"errorMessage":"[X] Your system is running python3 scripts with a bad locale setting: {PYTHON_ENCODING} (it should be UTF-8).","messagePattern":"\\[X\\] Your system is running python3 scripts with a bad locale setting: (.+?) \\(it should be UTF-8\\)\\.","errorType":"console","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"archivebox/misc/checks.py","lineNumber":182,"sourceCode":"        if blocking:\n            raise SystemExit(3)\n    return pending\n\n\ndef check_io_encoding():\n    PYTHON_ENCODING = (sys.__stdout__ or sys.stdout or sys.__stderr__ or sys.stderr).encoding.upper().replace(\"UTF8\", \"UTF-8\")\n\n    if PYTHON_ENCODING != \"UTF-8\":\n        print(\n            f\"[red][X] Your system is running python3 scripts with a bad locale setting: {PYTHON_ENCODING} (it should be UTF-8).[/red]\",\n            file=sys.stderr,\n        )\n        print('    To fix it, add the line \"export PYTHONIOENCODING=UTF-8\" to your ~/.bashrc file (without quotes)', file=sys.stderr)\n        print('    Or if you\\'re using ubuntu/debian, run \"dpkg-reconfigure locales\"', file=sys.stderr)\n        print(\"\")\n        print(\"    Confirm that it's fixed by opening a new shell and running:\", file=sys.stderr)\n        print('        python3 -c \"import sys; print(sys.stdout.encoding)\"   # should output UTF-8', file=sys.stderr)\n        raise SystemExit(2)\n\n\ndef check_not_root():\n    is_getting_help = \"-h\" in sys.argv or \"--help\" in sys.argv or \"help\" in sys.argv\n    is_getting_version = \"--version\" in sys.argv or \"version\" in sys.argv\n\n    if os.geteuid() == 0 and not (is_getting_help or is_getting_version):\n        print(\"[yellow][!] Running ArchiveBox as root is not recommended.[/yellow]\", file=sys.stderr)\n        print(\"    Root-owned DATA_DIR files may be inaccessible to non-root users later.\", file=sys.stderr)\n        print(\"        https://github.com/ArchiveBox/ArchiveBox/wiki/Security-Overview#do-not-run-as-root\", file=sys.stderr)\n\n\ndef is_archivebox_source_root(path: Path | str | None = None) -> bool:\n    \"\"\"Return whether path is the root of an ArchiveBox source checkout.\"\"\"\n    path = Path(path or os.getcwd()).resolve()\n    try:\n        return (path / \".git\").exists() and (path / \"archivebox\" / \"__init__.py\").is_file() and (path / \"pyproject.toml\").is_file()\n    except OSError:","sourceCodeStart":164,"sourceCodeEnd":200,"githubUrl":"https://github.com/ArchiveBox/ArchiveBox/blob/74564b28220090664f919479e82cbf454125fa34/archivebox/misc/checks.py#L164-L200","documentation":"check_io_encoding verifies the active stdout encoding is UTF-8, since ArchiveBox archives pages with arbitrary Unicode. If the resolved encoding (from sys.__stdout__/stdout/__stderr__/stderr) is anything other than UTF-8, it prints the offending encoding and fix instructions, then raises SystemExit(2).","triggerScenarios":"Running archivebox in an environment where Python's stdio encoding is non-UTF-8: POSIX/C locale over SSH, cron/systemd with minimal LANG, containers without locale set, or piping output in a shell whose locale is ASCII.","commonSituations":"SSH into a server with no LANG/LC_ALL set; cron jobs inheriting empty environment; Docker images lacking locales package; CI runners with C locale; older Debian/Ubuntu defaulting to ASCII.","solutions":["Add `export PYTHONIOENCODING=UTF-8` to your shell profile / cron / systemd unit environment","Set proper locale: `export LANG=C.UTF-8` (or `dpkg-reconfigure locales` on Debian/Ubuntu and choose a UTF-8 locale)","Fix it in Docker by setting ENV LANG=C.UTF-8 in the image or `environment:` in compose","Verify with `python3 -c \"import sys; print(sys.stdout.encoding)\"` in a new shell"],"exampleFix":"# before (crontab)\n0 * * * * archivebox update\n# after\n0 * * * * PYTHONIOENCODING=UTF-8 LANG=C.UTF-8 archivebox update","handlingStrategy":"validation","validationCode":"import sys, os\nenc = (sys.__stdout__ or sys.stdout).encoding or \"\"\nif enc.upper().replace(\"UTF8\", \"UTF-8\") != \"UTF-8\":\n    os.environ[\"PYTHONIOENCODING\"] = \"UTF-8\"\n    os.execv(sys.executable, [sys.executable] + sys.argv)  # relaunch with UTF-8","typeGuard":"def has_utf8_stdio() -> bool:\n    import sys\n    enc = (sys.__stdout__ or sys.stdout).encoding\n    return bool(enc) and enc.upper().replace(\"UTF8\", \"UTF-8\") == \"UTF-8\"","tryCatchPattern":"try:\n    run_archivebox_cmd(cmd)\nexcept SystemExit as e:\n    if e.code == 2 and \"bad locale setting\" in last_stderr():\n        env = {**os.environ, \"PYTHONIOENCODING\": \"UTF-8\", \"LANG\": \"C.UTF-8\"}\n        subprocess.run(cmd, env=env, check=True)\n    else:\n        raise","preventionTips":["Set LANG=C.UTF-8 and PYTHONIOENCODING=UTF-8 in shell profiles, cron, systemd, and Docker images","Verify `python3 -c \"import sys; print(sys.stdout.encoding)\"` prints UTF-8 in deployment shells","Reconfigure locales on Debian/Ubuntu (dpkg-reconfigure locales) for fresh servers"],"tags":["encoding","locale","environment","unicode"],"backgroundTag":"bad-locale-encoding","analyzedSha":"74564b28220090664f919479e82cbf454125fa34","analyzedAt":"2026-08-28T23:56:51.556Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}