Skip to main content

How to Resolve Python Pip "ImportError: cannot import name 'html5lib' from 'pip._vendor'"

When using pip (Python's package installer), especially on certain Linux distributions like Ubuntu with specific Python versions (e.g., Python 3.10 provided by the system), you might encounter the ImportError: cannot import name 'html5lib' from 'pip._vendor'. This error typically indicates an issue with the installed version of pip itself, where its vendored (internally bundled) dependencies are outdated or mismatched, often due to how the system's package manager (apt) manages Python components.

This guide explains the common causes for this pip internal error and provides effective solutions focused on upgrading pip correctly.

Understanding the Error: Pip's Vendored Dependencies​

To ensure pip can function reliably without depending on other packages being present in the environment, it "vendors" or bundles copies of its own dependencies (like requests, html5lib, six, etc.) within a special pip._vendor package. The html5lib library is used by pip for tasks like parsing HTML pages when searching for package links.

The error cannot import name 'html5lib' from 'pip._vendor' means that the version of pip being executed expects to find html5lib within its _vendor directory, but for some reason (often due to an incomplete or outdated pip installation, particularly one managed by the OS package manager), it cannot locate or correctly import it.

This is most commonly observed on systems like Ubuntu when using the pip that comes with the system-provided Python (e.g., /usr/bin/pip3 linked to Python 3.10 from apt).

Common Cause: Outdated or System-Managed pip​

  • System pip: Linux distributions often provide pip via their own package managers (e.g., python3-pip via apt). These system-managed versions can sometimes lag behind the latest releases from PyPI or have modifications that lead to internal inconsistencies, especially across Python minor version upgrades.
  • Outdated pip: An older version of pip might have an incomplete or differently structured _vendor package.

The most reliable way to get the latest official version of pip, especially when overriding a potentially problematic system-provided pip, is to use the get-pip.py bootstrap script from the Python Packaging Authority (PyPA).

  1. Download get-pip.py: 
    curl -sS https://bootstrap.pypa.io/get-pip.py -o get-pip.py
    # Or open https://bootstrap.pypa.io/get-pip.py in a browser and save the file.
  2. Run the script with the target Python interpreter: 
    # Replace 'python3' or 'python3.10' with your specific Python command
    python3 get-pip.py
    # If you need to upgrade the system pip and get permission errors:
    # sudo python3 get-pip.py
    This script will install or upgrade pip, setuptools, and wheel to their latest compatible versions for the specified Python interpreter, usually resolving issues with vendored dependencies. After running this, close and reopen your terminal.

Solution 2: Upgrade pip Using ensurepip​

The ensurepip module provides a way to bootstrap pip into a Python installation or virtual environment.

# Replace 'python3' as needed
python3 -m ensurepip --upgrade
# Then, ensure pip itself is fully upgraded using the newly bootstrapped/verified pip
python3 -m pip install --upgrade pip

This first ensures a baseline pip is correctly installed via ensurepip and then uses that pip to upgrade itself to the latest version from PyPI.

Solution 3: Use pythonX.Y -m pip to Target Specific Version​

If you have multiple Python versions, explicitly invoking pip via pythonX.Y -m pip ensures you are using the pip associated with that specific Python version. This can also bypass issues with how the shell resolves the standalone pip command.

  1. Identify your Python version: 
    python3 --version # e.g., Python 3.10.6
  2. Upgrade and use pip for that version: 
    # Replace 3.10 with your version
    python3.10 -m pip install --upgrade pip
    python3.10 -m pip install <package-name> # Now install your target package

Solution 4: Use a Virtual Environment (Best Practice)​

Using virtual environments is always the recommended approach for managing Python projects and their dependencies. This isolates your project and provides a clean installation of pip and other tools.

  1. Create: 
    # Replace 'python3' with your specific Python executable if needed
    python3 -m venv my_project_env
  2. Activate: 
    # Linux/macOS
    source my_project_env/bin/activate
    # Windows CMD
    # my_project_env\Scripts\activate.bat
    # Windows PowerShell
    # my_project_env\Scripts\Activate.ps1
  3. Install (inside the active venv): The pip inside a fresh venv is usually modern and self-contained. 
    # Prompt should show (my_project_env)
    pip install --upgrade pip # Optional: ensure latest pip in venv
    pip install <package-name>

This generally avoids issues caused by system-managed pip installations.

Alternative: OS-Specific pip Installation/Upgrade​

While generally less reliable than get-pip.py for fixing this specific vendored dependency error, you can try your OS package manager to install/reinstall python3-pip. However, this might just reinstall the same version that's causing the issue.

# Debian/Ubuntu (might reinstall the system-provided version)
sudo apt update
sudo apt install --reinstall python3-pip

# Fedora/CentOS/RHEL
# sudo dnf reinstall python3-pip

After this, you might still need to run python3 -m pip install --upgrade pip or get-pip.py to get the latest PyPI version of pip.

Conclusion​

The ImportError: cannot import name 'html5lib' from 'pip._vendor' usually indicates an issue with an outdated or inconsistent pip installation, particularly common with system-provided pip on Linux distributions like Ubuntu.

The most effective solutions are:

  1. Upgrade pip using the get-pip.py script: This installs the latest official version of pip directly from PyPA.
  2. Use python -m ensurepip --upgrade followed by python -m pip install --upgrade pip: Bootstraps and then upgrades pip.
  3. Use Virtual Environments: This provides an isolated, clean pip installation for your project.
  4. Explicitly use pythonX.Y -m pip: Ensures you're targeting the correct pip for your intended Python version.

By ensuring you have a clean, up-to-date installation of pip (preferably within a virtual environment or managed by get-pip.py for system Python), you can resolve these internal pip._vendor import errors.

Table of Contents