CompatPy

Find Python versions compatible with your project's dependencies.

CompatPy analyzes a Python project, checks its dependencies against PyPI metadata, and determines which Python versions are compatible with the dependency requirements.

• Discover dependencies from requirements.txt
• Discover dependencies from pyproject.toml
• Normalize dependency names using Python packaging conventions
• Parse common version constraints and specifier combinations
• Retrieve package metadata from PyPI
• Evaluate Python-version compatibility for dependency requirements
• Handle stable and prerelease package versions
• Support Python version exclusions
• Recommend compatible Python versions
• Provide a simple command-line interface

CompatPy is a focused compatibility checker for Python projects. It is useful for common dependency and Python-version checks, but it is not intended to be treated as a full dependency solver or a complete replacement for a production environment resolver.

Useful today:

• common dependency declarations in requirements.txt
• common dependency declarations in pyproject.toml
• standard specifier parsing for many requirements
• compatibility checks using published package metadata from PyPI

Known limitations:

• some advanced requirement forms are still partially supported or under active development
• direct URL and some VCS-style requirements may be limited or unevenly handled
• complex dependency graphs and edge-case metadata scenarios may not be fully covered
• results depend on the dependency metadata available from the packages being analyzed

Pre-built release assets are published on the GitHub Releases page.

The release workflow builds and uploads binaries for:

• Linux x86_64
• Linux ARM64
• Windows x86_64
• Windows ARM64
• macOS x86_64
• macOS ARM64

It also builds a Windows MSI installer for the x86_64 release.

Typical asset names look like:

compatpy-x86_64-unknown-linux-gnu.tar.gz
compatpy-aarch64-unknown-linux-gnu.tar.gz
compatpy-x86_64-pc-windows-msvc.zip
compatpy-aarch64-pc-windows-msvc.zip
compatpy-x86_64-apple-darwin.tar.gz
compatpy-aarch64-apple-darwin.tar.gz
compatpy-<version>.msi

For example, on Windows x86_64 you can download the zip archive or the MSI installer, then run the binary from PowerShell:

Expand-Archive compatpy-x86_64-pc-windows-msvc.zip -DestinationPath .\release
.\release\compatpy.exe "C:\path\to\your\project"

Alternatively, install the MSI and run compatpy directly from PowerShell.

If you have Rust installed:

cargo install --git https://github.com/oluxid/CompatPy.git

Or clone the repository and build it locally:

git clone https://github.com/oluxid/CompatPy.git
cd CompatPy
cargo build --release

The compiled executable will be located in:

target/release/

Pass the root directory of a Python project:

compatpy "C:\path\to\your\project"

For requirements with environment markers, provide a JSON file containing every standardized PEP 508 target-environment field. CompatPy does not infer target values from the machine running the analysis:

compatpy "C:\path\to\your\project" --target-environment .\target.json

The JSON file must include implementation_name, implementation_version, os_name, platform_machine, platform_python_implementation, platform_release, platform_system, platform_version, python_full_version, python_version, and sys_platform. For example:

{
  "implementation_name": "cpython",
  "implementation_version": "3.12.0",
  "os_name": "posix",
  "platform_machine": "x86_64",
  "platform_python_implementation": "CPython",
  "platform_release": "6.8.0",
  "platform_system": "Linux",
  "platform_version": "generic",
  "python_full_version": "3.12.0",
  "python_version": "3.12",
  "sys_platform": "linux"
}

When running a downloaded portable binary directly on Windows:

.\release\compatpy.exe "C:\path\to\your\project"

CompatPy will discover the project's dependencies, inspect their package metadata, and recommend Python versions that satisfy the declared requirements.

compatpy --help

compatpy --version

CompatPy follows a simple process:

Python project
      │
      ▼
Discover dependencies
      │
      ▼
Retrieve package metadata
      │
      ▼
Resolve dependency versions
      │
      ▼
Analyze Python compatibility
      │
      ▼
Recommend compatible Python versions

The result is based on the compatibility information available from the project's dependencies and their PyPI metadata.

No Rust installation is required when using a pre-built release binary.

An internet connection is required when CompatPy needs to retrieve package metadata from PyPI.

Building CompatPy from source requires:

• Rust 1.85 or newer
• Cargo
• Internet access for retrieving dependencies and PyPI metadata

Clone the repository:

git clone https://github.com/oluxid/CompatPy.git
cd CompatPy

Run the test suite:

cargo test

Build a release binary:

cargo build --release

Format the code:

cargo fmt

Want to help improve CompatPy? Pick an item from the roadmap and help move it forward!

Check the current implementation before starting work. For larger changes, open an issue to discuss the proposed approach first. Keep changes focused and include tests where appropriate. Update the roadmap when a feature is implemented and verified.

Not every roadmap item is a commitment or a release blocker. Contributions, bug reports, tests, and suggestions are all welcome.

CompatPy is licensed under the MIT License.

See LICENSE for the full license text.