pypa/pip · error · ConfigurationFileCouldNotBeLoaded

Configuration file contains invalid {locale_encoding} charac

Error message

Configuration file contains invalid {locale_encoding} characters in {fname}.

What it means

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.

Source

Thrown at src/pip/_internal/configuration.py:300

            items = parser.items(section)
            self._config[variant].setdefault(fname, {})
            self._config[variant][fname].update(self._normalized_keys(section, items))

        return parser

    def _construct_parser(self, fname: str) -> RawConfigParser:
        parser = configparser.RawConfigParser()
        # If there is no such file, don't bother reading it but create the
        # parser anyway, to hold the data.
        # Doing this is useful when modifying and saving files, where we don't
        # need to construct a parser.
        if os.path.exists(fname):
            locale_encoding = get_locale_encoding()
            try:
                parser.read(fname, encoding=locale_encoding)
            except UnicodeDecodeError:
                # See https://github.com/pypa/pip/issues/4963
                raise ConfigurationFileCouldNotBeLoaded(
                    reason=f"contains invalid {locale_encoding} characters",
                    fname=fname,
                )
            except configparser.Error as error:
                # See https://github.com/pypa/pip/issues/4893
                raise ConfigurationFileCouldNotBeLoaded(error=error)
        return parser

    def _load_environment_vars(self) -> None:
        """Loads configuration from environment variables"""
        self._config[kinds.ENV_VAR].setdefault(":env:", {})
        self._config[kinds.ENV_VAR][":env:"].update(
            self._normalized_keys(":env:", self.get_environ_vars())
        )

    def _normalized_keys(
        self, section: str, items: Iterable[tuple[str, Any]]
    ) -> dict[str, Any]:

View on GitHub (pinned to f399c37189)

Solutions

1. Re-save the config file as UTF-8 (no BOM) using a text editor.
2. Remove any non-ASCII characters from the config file, especially in values like URLs.
3. Set the PYTHONUTF8=1 environment variable to force UTF-8 mode, or align the system locale with the file encoding.
4. Validate the file encoding with `file -i <config>` and convert if needed (`iconv -f <old> -t UTF-8 <config> -o <config.new>`).

Example fix

# before: pip.ini saved as UTF-16
# fix: convert to UTF-8
iconv -f UTF-16 -t UTF-8 pip.ini -o pip.ini.utf8 && mv pip.ini.utf8 pip.ini

def validate_config_encoding(path: str) -> None:
    with open(path, 'rb') as f:
        data = f.read()
    try:
        data.decode('utf-8')
    except UnicodeDecodeError as e:
        raise ValueError(f'{path} is not valid UTF-8: {e}') from e

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• An error occurred while writing to the configuration file {f
• Failed to build one or more wheels
• Key does not contain dot separated section and key. Perhaps
• Got invalid value for load_only - should be one of {}
• No such key - {orig_key}

AI-assisted analysis of pypa/pip@f399c37189 (2026-08-08). Data as JSON: /api/errors/102a54994724ea60. Report an issue: GitHub.