sodcalculator

10 Tech How-To

Python setup.py egg_info Failed with Error Code

Guide 10-48138 · Updated · Step by step

When you run python setup.py egg_info and it fails with an error code, the cause is almost always a missing build dependency, an incompatible Python version, or a network/pip index problem — not a bug in your code. The fix is to identify the exact error message, install the missing prerequisite, and retry; this article explains the common causes and step-by-step solutions.

What Does setup.py egg_info Actually Do?

setup.py egg_info is a setuptools command that generates the .egg-info directory — a metadata folder containing the package name, version, dependencies, and entry points. It is run automatically when you install a package with pip install . or pip install -e ., and it is also invoked when pip builds a package from source. The command parses setup.py, reads the install_requires list, and creates the metadata files. If any step fails — a syntax error in setup.py, a missing setuptools version, or an unavailable dependency — the command exits with a non-zero error code.

Most Common Causes of egg_info Failure

  • Missing build dependencies — packages like setuptools, wheel, or pkg-config are not installed or are too old.
  • Syntax error in setup.py — a typo, undefined variable, or invalid Python code causes the script to crash.
  • Incompatible Python version — the package may require a newer or older Python than the one you are using.
  • Network issues — when egg_info tries to fetch dependencies from PyPI and the connection fails, it aborts.
  • Missing system libraries — for packages with C extensions, headers like python3-dev or libffi-dev are required.
  • Permission errors — writing the .egg-info directory to a read-only location fails.

Step-by-Step Troubleshooting

  1. Read the full error message. The last lines usually contain the actual exception (e.g., ModuleNotFoundError: No module named 'wheel'). Scroll up — the error code alone (like 1 or 2) is not enough.
  2. Upgrade setuptools and wheel. Run pip install --upgrade setuptools wheel. An outdated setuptools is the single most common cause.
  3. Check your Python version. Run python --version. If the package requires Python 3.8+ and you have 3.6, upgrade or use a virtual environment with the correct interpreter.
  4. Install system dependencies. On Ubuntu/Debian, run sudo apt install python3-dev build-essential. On Windows, ensure you have the Microsoft C++ Build Tools. On macOS, install Xcode Command Line Tools.
  5. Test setup.py directly. Run python setup.py --name to see if the script parses correctly. If it crashes, the error is in your setup.py code.
  6. Use a virtual environment. Create a fresh venv with python -m venv venv, activate it, and retry. This isolates dependency conflicts.
  7. Retry with verbose output. Use pip install -v . to see every step pip runs, including the exact egg_info invocation.

Common Error Messages and Their Fixes

  • ModuleNotFoundError: No module named 'setuptools' — Install setuptools: pip install setuptools.
  • error: [Errno 13] Permission denied — Use --user or a virtual environment, or fix directory permissions.
  • Invalid requirement: 'package>=1.0' — The install_requires list has a malformed specifier. Check for typos or missing commas.
  • CompileError: command 'gcc' failed — Install the C compiler and Python headers (see step 4 above).
  • Could not find a version that satisfies the requirement — The dependency does not exist on PyPI or the index is not reachable. Check your network and pip index URL.

Why Does pip Sometimes Use egg_info Even When a Wheel Exists?

Pip prefers to install a pre-built wheel (a .whl file) because it skips the build step. However, if the package does not provide a wheel for your platform or Python version, pip falls back to building from source, which invokes setup.py egg_info. This is common for packages with C extensions that are not pre-compiled for every OS. To avoid this, you can install the binary wheel if available, or use a package manager like conda that provides pre-built binaries.

How to Prevent egg_info Failures in Your Own Package

If you are the package author, you can make your setup.py more robust:

  • Use setuptools.setup() with a pyproject.toml file (PEP 517) instead of a bare setup.py. This ensures the build environment has the required tools.
  • Declare all dependencies in install_requires and include a setup_requires list for build-time dependencies.
  • Add a python_requires field to specify the supported Python versions — this prevents users on incompatible versions from even attempting the build.
  • Test the build in a clean virtual environment before publishing.

Frequently Asked Questions

What does “error code 1” mean in setup.py egg_info?

Error code 1 is the generic exit code for any unhandled exception. It tells you nothing specific — you must read the traceback above it to find the real cause. The most common underlying issues are missing dependencies, syntax errors, or permission problems.

How do I fix “egg_info” failing when installing a package from GitHub?

Installing directly from a Git URL (pip install git+https://...) requires the repository to have a valid setup.py or pyproject.toml. First, clone the repo manually and run python setup.py egg_info to see the error. Then follow the same troubleshooting steps — often the repo requires a newer setuptools or a specific Python version.

Can I skip egg_info and install directly?

No, egg_info is a mandatory step when building from source. However, if a wheel is available for your platform, pip will use it and skip the build entirely. You can force pip to use a wheel by specifying --only-binary :all:, but that will fail if no wheel exists.

Why does egg_info fail on Windows but not on Linux?

Often because the package has C extensions that require a compiler. Windows needs the Microsoft C++ Build Tools, while Linux typically has GCC pre-installed. Also, some packages use Unix-specific commands in setup.py that do not work on Windows.

Is it safe to delete the .egg-info folder?

Yes, the .egg-info directory is generated automatically and is safe to delete. It is not part of your source code — it is build metadata. Deleting it will force a fresh regeneration on the next build, which can sometimes resolve stale metadata issues.

Related

General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.

More in this bed

The whole Tech How-To bed →