{"record":{"id":"102a54994724ea60","repo":"pypa/pip","slug":"configuration-file-contains-invalid-locale-encodi","errorCode":null,"errorMessage":"Configuration file contains invalid {locale_encoding} characters in {fname}.","messagePattern":"Configuration file contains invalid (.+?) characters in (.+?)\\.","errorType":"exception","errorClass":"ConfigurationFileCouldNotBeLoaded","httpStatus":null,"severity":"error","filePath":"src/pip/_internal/configuration.py","lineNumber":300,"sourceCode":"            items = parser.items(section)\n            self._config[variant].setdefault(fname, {})\n            self._config[variant][fname].update(self._normalized_keys(section, items))\n\n        return parser\n\n    def _construct_parser(self, fname: str) -> RawConfigParser:\n        parser = configparser.RawConfigParser()\n        # If there is no such file, don't bother reading it but create the\n        # parser anyway, to hold the data.\n        # Doing this is useful when modifying and saving files, where we don't\n        # need to construct a parser.\n        if os.path.exists(fname):\n            locale_encoding = get_locale_encoding()\n            try:\n                parser.read(fname, encoding=locale_encoding)\n            except UnicodeDecodeError:\n                # See https://github.com/pypa/pip/issues/4963\n                raise ConfigurationFileCouldNotBeLoaded(\n                    reason=f\"contains invalid {locale_encoding} characters\",\n                    fname=fname,\n                )\n            except configparser.Error as error:\n                # See https://github.com/pypa/pip/issues/4893\n                raise ConfigurationFileCouldNotBeLoaded(error=error)\n        return parser\n\n    def _load_environment_vars(self) -> None:\n        \"\"\"Loads configuration from environment variables\"\"\"\n        self._config[kinds.ENV_VAR].setdefault(\":env:\", {})\n        self._config[kinds.ENV_VAR][\":env:\"].update(\n            self._normalized_keys(\":env:\", self.get_environ_vars())\n        )\n\n    def _normalized_keys(\n        self, section: str, items: Iterable[tuple[str, Any]]\n    ) -> dict[str, Any]:","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/pypa/pip/blob/f399c3718970b1b0e2478dac5296eb62679a9b86/src/pip/_internal/configuration.py#L282-L318","documentation":"Raised by Configuration._construct_parser() when reading a config file with the locale encoding raises UnicodeDecodeError. This means the file contains bytes that are not valid in the detected locale encoding (commonly UTF-8 or cp1252). pip wraps this as a ConfigurationFileCouldNotBeLoaded so the file path and offending encoding are reported clearly.","triggerScenarios":"A pip.conf or pip.ini saved in one encoding (e.g. UTF-16, Latin-1 with special bytes) but read under a different locale encoding; files with BOM markers or mojibake from copy-paste across systems; Windows files with cp1252-specific bytes read on a UTF-8 locale.","commonSituations":"Editing pip.ini on Windows in an editor that saves as UTF-16; transferring config files between Windows and Linux; config files containing non-ASCII characters (e.g. in a URL with special chars) saved with an incompatible encoding.","solutions":["Re-save the config file as UTF-8 (no BOM) using a text editor.","Remove any non-ASCII characters from the config file, especially in values like URLs.","Set the PYTHONUTF8=1 environment variable to force UTF-8 mode, or align the system locale with the file encoding.","Validate the file encoding with `file -i <config>` and convert if needed (`iconv -f <old> -t UTF-8 <config> -o <config.new>`)."],"exampleFix":"# before: pip.ini saved as UTF-16\n# fix: convert to UTF-8\niconv -f UTF-16 -t UTF-8 pip.ini -o pip.ini.utf8 && mv pip.ini.utf8 pip.ini","handlingStrategy":"validation","validationCode":"def validate_config_encoding(path: str) -> None:\n    with open(path, 'rb') as f:\n        data = f.read()\n    try:\n        data.decode('utf-8')\n    except UnicodeDecodeError as e:\n        raise ValueError(f'{path} is not valid UTF-8: {e}') from e\n","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Save pip config files as UTF-8 without BOM.","Avoid non-ASCII characters in config values.","Set PYTHONUTF8=1 in environments with mismatched locales."],"tags":["pip","config","encoding","unicode","filesystem"],"backgroundTag":null,"analyzedSha":"f399c3718970b1b0e2478dac5296eb62679a9b86","analyzedAt":"2026-08-08T23:01:42.227Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}