{"id":7073,"library":"change-wheel-version","title":"change-wheel-version","description":"change-wheel-version is a Python utility that modifies the version string within the metadata of an existing wheel (.whl) file. It's particularly useful for adding local version identifiers to custom-built wheels without altering the original package's build process. The library is active, with its latest version being 0.6.0, released in September 2024. Its release cadence is infrequent, driven by specific needs for wheel metadata manipulation.","status":"active","version":"0.6.0","language":"en","source_language":"en","source_url":"https://github.com/hauntsaninja/change_wheel_version","tags":["packaging","wheel","versioning","build-process","cli-tool"],"install":[{"cmd":"pip install change-wheel-version","lang":"bash","label":"Install with pip"},{"cmd":"pipx install change-wheel-version","lang":"bash","label":"Install and run with pipx (recommended for CLI tools)"}],"dependencies":[{"reason":"Required runtime environment.","package":"python","optional":false}],"imports":[{"note":"The tool is designed for command-line execution, not direct Python imports for API usage.","symbol":"change-wheel-version","correct":"This library is primarily a command-line tool. Direct programmatic import is not a commonly exposed or documented API. It is typically executed via 'pipx run change_wheel_version' or by running the installed script."}],"quickstart":{"code":"import os\nimport subprocess\nimport tempfile\nimport shutil\n\n# 1. Create a dummy Python project structure\nproject_name = \"my_dummy_package\"\noriginal_version = \"0.1.0\"\nmodified_version = \"0.1.0+local.123\"\n\ntry:\n    with tempfile.TemporaryDirectory() as tmpdir:\n        project_dir = os.path.join(tmpdir, project_name)\n        os.makedirs(project_dir)\n\n        # Create setup.py\n        with open(os.path.join(project_dir, \"setup.py\"), \"w\") as f:\n            f.write(f'''\nfrom setuptools import setup, find_packages\n\nsetup(\n    name='{project_name}',\n    version='{original_version}',\n    packages=find_packages(),\n    description='A dummy package for testing change-wheel-version',\n)\n''')\n\n        # Create __init__.py\n        os.makedirs(os.path.join(project_dir, project_name))\n        with open(os.path.join(project_dir, project_name, \"__init__.py\"), \"w\") as f:\n            f.write(\"__version__ = f'{original_version}'\")\n\n        # Change to project directory\n        os.chdir(project_dir)\n\n        # 2. Build the original wheel\n        print(f\"\\nBuilding initial wheel for {project_name}-{original_version}...\")\n        subprocess.run([\"python\", \"-m\", \"build\", \"--wheel\"], check=True, capture_output=True)\n\n        # Find the generated wheel file\n        dist_dir = os.path.join(project_dir, \"dist\")\n        original_wheel = [f for f in os.listdir(dist_dir) if f.endswith('.whl') and original_version in f][0]\n        original_wheel_path = os.path.join(dist_dir, original_wheel)\n        print(f\"Original wheel created: {original_wheel_path}\")\n\n        # 3. Use change-wheel-version to modify the wheel's version\n        modified_wheel_name = original_wheel.replace(original_version, modified_version)\n        modified_wheel_path = os.path.join(dist_dir, modified_wheel_name)\n\n        print(f\"\\nChanging version of {original_wheel} to {modified_version}...\")\n        subprocess.run(\n            [\"pipx\", \"run\", \"change-wheel-version\", original_wheel_path, \"--new-version\", modified_version],\n            check=True, capture_output=True\n        )\n\n        # The tool renames the file in place by default if --output is not specified\n        # So we expect the original wheel to be renamed.\n        if os.path.exists(original_wheel_path) and not os.path.exists(modified_wheel_path):\n             # Fallback if the tool doesn't rename exactly as expected based on new version, e.g. if original had build tags already\n             # For simplicity, we'll try to find the new file, or assume it overwrote.\n             # More robust would be to use --output.\n             print(\"Attempting to find the newly named wheel...\")\n             new_wheels = [f for f in os.listdir(dist_dir) if f.endswith('.whl') and modified_version in f]\n             if new_wheels:\n                 modified_wheel_path = os.path.join(dist_dir, new_wheels[0])\n             else:\n                 raise FileNotFoundError(\"Modified wheel not found with expected version in name.\")\n\n        print(f\"Modified wheel: {modified_wheel_path}\")\n\n        # 4. Verify the new version using 'wheel info'\n        print(\"\\nVerifying the new wheel's version...\")\n        result = subprocess.run([\"pipx\", \"run\", \"wheel\", \"info\", modified_wheel_path], capture_output=True, text=True, check=True)\n        print(result.stdout)\n\n        if f\"Version: {modified_version}\" in result.stdout:\n            print(\"\\nSuccessfully changed and verified the wheel version!\")\n        else:\n            print(\"\\nFailed to verify the wheel version.\")\n\n        print(f\"Cleaning up temporary directory: {tmpdir}\")\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error executing command: {e.cmd}\")\n    print(f\"Stdout: {e.stdout.decode()}\")\n    print(f\"Stderr: {e.stderr.decode()}\")\nexcept FileNotFoundError as e:\n    print(f\"File not found error: {e}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\n","lang":"python","description":"This quickstart demonstrates how to use `change-wheel-version` to modify the version of an existing wheel file. It first creates a minimal dummy Python package, builds it into a wheel, then applies `change-wheel-version` to update the wheel's metadata, and finally verifies the change using the `wheel info` command. This requires `pipx` and `build` to be installed."},"warnings":[{"fix":"Ensure that if your project relies on `__version__` or similar variables within its code, these are updated separately or generated at build time.","message":"change-wheel-version only alters the version string in the wheel's metadata (e.g., in the .dist-info directory and the filename). It does NOT modify any version numbers hardcoded within the Python source files inside the wheel. Developers must manually update in-code versions if desired.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always consider using the `--output <new_filename.whl>` option to explicitly control the name and location of the modified wheel file. This is especially important in automated build environments or when applying complex version suffixes.","message":"When using `change-wheel-version` without the `--output` option, the tool attempts to rename the original wheel file in place. If the new version string results in an invalid filename for the operating system or conflicts with existing files, this operation might fail or result in unexpected file names.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install pipx first: `python3 -m pip install --user pipx` and then ensure your PATH is updated, typically by running `python3 -m pipx ensurepath`.","cause":"The 'pipx' tool, which is recommended for running change-wheel-version as a standalone application, is not installed or not in your system's PATH.","error":"Command 'pipx' not found"},{"fix":"Verify that your project builds successfully and generates a wheel file. Check the `dist/` directory (or wherever your build system outputs wheels) for the correct filename. Use absolute paths or ensure your current working directory is correct when running the command.","cause":"The specified wheel file does not exist at the provided path, or the path is incorrect. This can happen if the wheel was not built, or if the `build` command placed it in a different directory.","error":"No such file or directory: 'dist/<your_wheel_file>.whl'"},{"fix":"Ensure your new version string follows PEP 440 guidelines. For example, local versions should start with a `+` (e.g., `1.0.0+local.build1`). Refer to the PEP 440 specification for valid version formats.","cause":"The version string provided to `change-wheel-version` via `--new-version` does not conform to PEP 440 (e.g., contains illegal characters, incorrect format for local versions, etc.).","error":"ERROR: Invalid version: '<invalid_version_string>'"}]}