ThisCalculator

Everyday

Inspect a Python Wheel: Contents & Metadata

Updated · Standard formula, shown below

This guide shows you how to look inside a Python wheel file to see exactly what files it contains and what metadata (name, version, dependencies, entry points) it declares. You’ll learn three reliable methods: using the built-in zipfile module, the dedicated wheel command-line tool, and a quick unzip trick. No prior experience with wheel internals is needed—just a terminal and Python installed.

What You’ll Need

  • Python 3.6 or newer installed on your system.
  • A wheel file (.whl) you want to inspect. You can download one from PyPI or find one in your local site-packages directory.
  • Optional: the wheel package installed (pip install wheel) for the command-line method.

Step-by-Step

Method 1: Using Python’s zipfile Module (No Extra Tools)

  1. Open a terminal or command prompt.
  2. Start a Python interactive session by typing python (or python3 on some systems) and pressing Enter.
  3. Import the zipfile module: import zipfile
  4. Open the wheel file. Replace path/to/your.whl with the actual path:
    with zipfile.ZipFile('path/to/your.whl') as z:
  5. List all contents by printing z.namelist() inside the with block. This shows every file and directory in the wheel.
  6. To see metadata, look for the .dist-info directory. Read the METADATA file by accessing it:
    print(z.read('name_of_package-version.dist-info/METADATA').decode())
    Replace the filename with whatever appears in the namelist output (usually package_name-version.dist-info/METADATA).
  7. To see the dependency list specifically, search the METADATA output for lines starting with Requires-Dist:. You can also read the entry_points.txt file from the same dist-info folder to see console scripts and plugin entry points.

Method 2: Using the wheel Command-Line Tool

  1. Install the wheel package if you haven’t: pip install wheel
  2. In your terminal, navigate to the directory containing the wheel file.
  3. Run wheel unpack your_file.whl to extract the contents into a folder named after the package. This gives you a full directory tree you can browse normally.
  4. Alternatively, run wheel show your_file.whl to display metadata directly in the terminal without extracting anything. This shows name, version, summary, and dependencies.

Method 3: Using unzip (Quick Look)

  1. On Linux or macOS, use unzip -l your_file.whl to list contents without extracting.
  2. To extract just the metadata, run unzip -p your_file.whl '*.dist-info/METADATA' (the -p flag prints to stdout).
  3. On Windows, you can right-click the wheel file and choose “Extract All” if you have a zip utility installed, but the command-line methods above are more precise.

Common Mistakes

  • Confusing wheel with a source distribution: A .tar.gz or .zip from PyPI is a source distribution (sdist), not a wheel. The methods here work only on .whl files.
  • Looking for metadata in the wrong place: The .dist-info folder is always at the top level of the wheel, not inside a package directory. If you don’t see it, you might be looking at a different file type.
  • Using zipfile without closing: If you don’t use a with block, call z.close() to avoid file locks, especially on Windows.
  • Assuming the wheel name matches the package name: The filename includes version and Python/OS tags (e.g., numpy-1.24.3-cp311-cp311-win_amd64.whl). The dist-info folder will use the canonical name, which may have underscores instead of hyphens.

Tips

  • Use z.namelist() to quickly see if the wheel contains compiled extensions (files ending in .so, .pyd, or .dll). This tells you if it’s a binary wheel or pure Python.
  • Check the WHEEL file inside the dist-info folder to see the wheel specification version and whether it’s universal (works on both Python 2 and 3) or platform-specific.
  • If you want to see the exact dependencies with version ranges, look at Requires-Dist lines in METADATA. Each line is one dependency, and they often include environment markers like python_version < '3.8'.
  • For a full metadata dump, use import importlib.metadata; print(importlib.metadata.metadata('package_name')) after installing the wheel, but that only works if it's installed in your environment.
  • To inspect a wheel without extracting it to disk, use zipfile in a one-liner: python -c "import zipfile,sys; z=zipfile.ZipFile(sys.argv[1]); print('\n'.join(z.namelist()))" your.whl

Troubleshooting

  • “No such file or directory” when opening the wheel: Double-check the path. If the wheel is in your Downloads folder, use the full path or navigate to that folder first.
  • The METADATA file doesn't exist: Some very old or malformed wheels might have a different structure. Try listing all files and look for anything ending in .dist-info or .egg-info. The latter is rare but possible.
  • Permission denied when using wheel unpack: On Linux/macOS, ensure the file is readable. If you're extracting to a system directory, use sudo or extract to your home directory.
  • Encoding errors when printing METADATA: The metadata is UTF-8, but your terminal might not handle some characters. Use errors='replace' in the decode call: .decode('utf-8', errors='replace').
  • wheel command not found: The wheel package may not be installed. Run pip install wheel or use the zipfile method instead.

Frequently Asked Questions

What exactly is a wheel file?

A wheel is a ZIP-based archive that contains a Python package's code and metadata. It's designed to be installed directly without needing a build step, making installation faster and more reliable.

How do I see a wheel's dependencies without installing it?

Read the METADATA file inside the .dist-info folder. Lines starting with Requires-Dist: list each dependency. You can also use wheel show your_file.whl to get a formatted summary.

Can I edit the contents of a wheel?

Technically yes, but it's not recommended. You can extract, modify, and re-zip, but you must preserve the exact structure and update any checksums if present. A simpler approach is to rebuild the wheel from source using pip wheel ..

What's the difference between a wheel and a source distribution?

A source distribution (.tar.gz) contains source code that must be compiled during installation. A wheel is pre-built and contains ready-to-use files. Wheels are faster to install and don't require a compiler.

How do I check if a wheel is compatible with my Python version?

Look at the filename: it includes a tag like cp39 (CPython 3.9) or py3 (any Python 3). The WHEEL file inside the dist-info also lists supported tags. If the tag doesn't match your Python version, installation will fail.

Can I inspect a wheel on a machine without Python?

Yes, since a wheel is just a ZIP file, you can use any ZIP extraction tool (like 7-Zip or the built-in Windows Explorer) to view its contents. However, you won't be able to read the metadata as conveniently as with Python's zipfile module.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.