Skip to main content

How to Resolve Python "ModuleNotFoundError: No module named 'setuptools'/'setuptools_rust'"

setuptools is a fundamental package in the Python ecosystem, essential for building, distributing, and installing Python packages (often used alongside pip and wheel). While typically bundled with Python or installed with pip, you might encounter ModuleNotFoundError: No module named 'setuptools'. Similarly, when working with projects involving Rust extensions, you might see ModuleNotFoundError: No module named 'setuptools_rust'.

This guide explains the causes for these errors and provides standard solutions, focusing on installation, upgrades, and environment checks.

Understanding the Errors: Build System Dependencies​

  • setuptools: Provides the foundation for packaging Python projects. It's needed by pip to install packages (especially those using setup.py) and is required by many build backends. While often present, it can sometimes be missing or outdated, especially in minimal installations or older environments.
  • setuptools_rust: A setuptools extension specifically designed to help build Python packages that include Rust code (using tools like cargo). It needs to be installed separately when working with such projects.

The ModuleNotFoundError for either indicates that the Python environment running your command (like pip install or python setup.py) cannot find the specified build tool module.

Error 1: ModuleNotFoundError: No module named 'setuptools'​

Cause: Missing or Corrupted setuptools​

Your Python environment simply lacks the setuptools package, or the existing installation is broken. This is less common with modern Python/pip installations but can occur.

Ensure you have the latest versions of pip, setuptools, and wheel (often needed together for building packages). Run this in your activated virtual environment or system terminal:

# Upgrade pip, setuptools, and wheel
python -m pip install --upgrade pip setuptools wheel

# Or use python3 if needed
python3 -m pip install --upgrade pip setuptools wheel

# Or use py (Windows)
py -m pip install --upgrade pip setuptools wheel

This command ensures all three core packaging tools are present and up-to-date. Often, just upgrading pip might bring in a compatible setuptools, but upgrading all three explicitly is safer.

Solution 2: Use get-pip.py Script​

The official get-pip.py script bootstraps pip installation and typically ensures setuptools and wheel are installed alongside it.

  1. Download get-pip.py from https://bootstrap.pypa.io/get-pip.py (Right-click -> Save As).
  2. Open your terminal in the download directory.
  3. Run the script: 
    python get-pip.py
    # Or:
    python3 get-pip.py
    # Or (Windows) 
    py get-pip.py

Solution 3: Recreate Virtual Environment​

Modern Python versions (3.3+) include venv, which automatically installs pip and usually setuptools into new virtual environments. If you suspect your current environment is broken, recreating it can fix the issue.

Ubuntu/Debian Specific: python3-setuptools​

On Debian/Ubuntu, if using the system's Python managed by apt, setuptools might be in a separate package.

sudo apt update
sudo apt install python3-setuptools

However, managing packages via pip within a virtual environment is generally recommended over relying on system apt packages for Python libraries.

Error 2: ModuleNotFoundError: No module named 'setuptools_rust'​

This error specifically occurs when trying to build or install a Python package that requires compiling Rust code via setuptools_rust, but that extension package is not installed.

Cause: Missing setuptools-rust Package or Outdated pip​

  • You haven't installed the setuptools-rust package.
  • Your pip version might be too old to correctly handle the build dependencies specified by the package you're trying to install.

Solution 1: Upgrade pip (Important First Step)​

An up-to-date pip is crucial for handling modern build requirements. Ensure pip is upgraded first:

python -m pip install --upgrade pip
# Or: 
python3 -m pip install --upgrade pip

Solution 2: Install setuptools-rust via pip​

After upgrading pip, install setuptools-rust itself:

pip install setuptools-rust

# Or use pip3 / python -m pip / py -m pip as needed
pip3 install setuptools-rust
python -m pip install setuptools-rust

# Use --user or sudo only if necessary and not using a virtual env
pip install setuptools-rust --user
sudo pip3 install setuptools-rust

Solution 3: Ensure setuptools is Also Present/Up-to-date​

setuptools-rust depends on setuptools. While pip should handle this dependency, explicitly ensuring setuptools is up-to-date (as per Solution 2.2) can sometimes help resolve obscure issues.

python -m pip install --upgrade setuptools setuptools-rust

General Troubleshooting for Both Errors​

These steps apply if the initial solutions don't work:

Verify Active Python Environment (Virtual Env, IDE)​

This is the most common source of persistent ModuleNotFoundErrors.

  • Terminal: Is your virtual environment activated? Does the (venv) prefix appear in your prompt?
  • IDE: Is the IDE's selected Python Interpreter pointing to the Python executable inside your virtual environment? (Use "Python: Select Interpreter" in VS Code; check Interpreter settings in PyCharm).

Check Installation (pip show)​

Verify if the package (setuptools or setuptools-rust) is actually installed in the active environment:

pip show setuptools
pip show setuptools-rust

# Or: 
python -m pip show setuptools
python -m pip show setuptools-rust

Check the Location: path shown. Does it belong to your active virtual environment?

Reinstall Packages​

Force a reinstall if you suspect corruption:

pip uninstall setuptools setuptools-rust            # Uninstall (use -y to skip prompt)
pip install --upgrade setuptools setuptools-rust    # Reinstall

Avoid Filename/Variable Shadowing​

Ensure you don't have files named setuptools.py or setuptools_rust.py in your project, or variables with those names, as they can interfere with imports.

Conclusion​

  • ModuleNotFoundError: No module named 'setuptools': Usually means the core setuptools package is missing or broken in your environment. Solution: Upgrade pip, setuptools, and wheel (python -m pip install --upgrade pip setuptools wheel). On Debian/Ubuntu, you might need sudo apt install python3-setuptools if using the system Python directly. Recreating a virtual environment often helps.
  • ModuleNotFoundError: No module named 'setuptools_rust': Means the extension for building Rust components is missing. Solution: First, upgrade pip (python -m pip install --upgrade pip), then install the package (pip install setuptools-rust). Ensure setuptools itself is also installed.

For both errors, verifying that you are working within the correct, activated virtual environment and that your IDE is using that same environment's interpreter is crucial for resolving persistent issues.

Table of Contents