Proposal: Release a `capstone6` package for the next major version

[patryk4815]

Hi!

I’d like to propose that the next major version of Capstone, which introduces extensive breaking changes, be released under a new PyPI package name, capstone6, rather than overwriting the existing capstone package.

Here are the main reasons for this approach:

1. Breaking changes are too extensive

The upcoming version contains major API and semantic changes that make backward compatibility with capstone 5.x infeasible. Attempting to maintain a compatibility layer would either:

• Introduce significant maintenance overhead, or
• Result in a compromised API that is confusing for users.

Releasing a separate package signals clearly that this is a next-generation API.

---

2. Python packaging model limitations

Python packages are identified by their top-level import name. Two versions of capstone cannot coexist in the same environment.

By creating a new package (capstone6), users and downstream projects can install both versions side-by-side

---

3. Compatibility with Linux distributions

Debian, Arch, and other distros ignore requirements.txt constraints and package libraries system-wide.

If capstone v6 overwrites capstone v5, this can lead to:

• Build failures for downstream packages depending on capstone v5
• Frustration for system package maintainers
• Delayed adoption of the new major version

A new package avoids these issues entirely.

---

This approach minimizes user friction, supports distro maintainers, and avoids technical debt from compatibility shims.

Thank you for considering this proposal!

[Rot127]

cc @Antelox

[wtdcode]

Some points:

• Maintaining two packages adds additional overhead.
• This also confuses users, as they can no longer update by pip install -U capstone. I do think the semantic version has already warned users that the API could probably change by bumping 5.x to 6.x.
• From what I could tell, for the cases listed specifically:
  • Distro maintainers: They can always point the dependency to a specific capstone version, like 5.0.6-1. So the only bad thing I could see is that the migration from v5 to v6 needs to refresh all packages that rely on v5. But honestly, in that case, a capstone6 is possible with the distro as well, instead of having it on our side, like libunicorn2.
  • Users with pyproject.toml/setup.py/setup.cfg: They can always specify the version they wish to use, including the option to lock to an older version.

[Antelox]

The releases follow the SemVer specs which supposes breaking changes of APIs when there is a major release. So 5.0.0 -> 6.0.0 is a major release and you would expect something can break on your projects.

Speaking of python, there are virtual environments to work with when you need to deal with specific versions of packages. This means that if you need to run different projects that use different capstone versions, you need to create separate venvs, each with the required version of capstone.

Regarding the building of capstone, also here you can just stick to download from release page the version you need. If you need the wheel packages, they are on PyPi and you don't need to build by yourself. You can just request to pip install specific version and use a constraint

capstone<6.0.0

In summary nothing gets overwritten, you can always control package version with proper project requirements (i.e. check out uv project that offers a way to create lock files to keep sync a venv with specific package versions: https://docs.astral.sh/uv/guides/projects/)

[patryk4815]

• Distro maintainers: They can always point the dependency to a specific capstone version, like 5.0.6-1. So the only bad thing I could see is that the migration from v5 to v6 needs to refresh all packages that rely on v5. But honestly, in that case, a capstone6 is possible with the distro as well, instead of having it on our side, like libunicorn2.

yes, but you can't use capstone6 on a library that uses capstone v5 because they are not compatible.
capstone6 has done too many breaking changes to be called compatible as "capstone", for me it is already a separate lib with a separate API

• Users with pyproject.toml/setup.py/setup.cfg: They can always specify the version they wish to use, including the option to lock to an older version.

Not true for any distro. They always skip that.

Speaking of python, there are virtual environments to work with when you need to deal with specific versions of packages

Not true, you can use library that use capstone v5 and other library use v6 - but can't install capstone v5 and v6 in same time

Maybe you shouldn't release capstone v6, but make capstone v6 as a compact version, so that there's one release cycle with backward compatibility and deprecated warnings. And only from capstone v7 onwards should you remove these options.

[Rot127]

yes, but you can't use capstone6 on a library that uses capstone v5 because they are not compatible.
capstone6 has done too many breaking changes to be called compatible as "capstone", for me it is already a separate lib with a separate API

For my understanding, have you used Capstone pre-v5? As far as I can tell Capstone v4 had also breaking changes to v5 or v3. How did you deal with those?

[Antelox]

Not true, you can use library that use capstone v5 and other library use v6 - but can't install capstone v5 and v6 in same time

You are saying you can not install capstone v5 on venv1 and capstone v6 on venv2, both virtual environments on same system?

[patryk4815]

You are saying you can not install capstone v5 on venv1 and capstone v6 on venv2, both virtual environments on same system?

@Antelox No, you’re still missing the core issues.
First, you cannot install Capstone v5 and v6 side by side in the same environment because they use the same top-level import name (capstone). Python does not allow two packages with the same module name to coexist.

Second, Capstone v6 is not backward compatible. Any library written for v5 will break immediately if v6 is installed, and there is no deprecated mechanism in Capstone to smooth this transition. You literally cannot warn users or auto-handle the migration-they will just hit import errors or broken APIs.

Combine these two points, and you get a situation where every user, every library, and every distribution is potentially broken if v6 replaces v5 under the same package name. This is why capstone6 as a separate package is not just a suggestion - it’s the only sane option.

For example I can't install pwndbg (they use capstone v6) and ROPgadget (they use capstone v5) in same venv. They are used as library in my venv.

ref: https://bugs.gentoo.org/967775#c4

[Rot127]

@patryk4815 I can take a closer look tomorrow. Just some quick answers for now.

Any library written for v5 will break immediately if v6 is installed

Is it breaking that quickly because of the ARM64 renaming?
If so, that part is still missing indeed. I wanted to add a ARM64 compatibility layer for Python before the next release. But this would just help with not renaming. The semantics below still changed. As it often happened before with v3 -> v4 -> v5.

Also, can you remember how you did it back then with the v4 -> v5 switch? Because it must have been the same problem. There was no rename, but there were many breaking changes in between (less visible than the ARM64 -> AArch64 though).

[patryk4815]

Also, can you remember how you did it back then with the v4 -> v5 switch?

I don't remember well, but this switch took a lot of time waiting for everybody to upgrade

@Rot127 I think that would be nice for 1 release cycle:

# capstone/__init__.py

CS_ARCH_AARCH64 = 1337

import warnings

def __getattr__(name):
    if name == "CS_ARCH_ARM64":
        warnings.warn(
            "CS_ARCH_ARM64 is deprecated, use CS_ARCH_AARCH64 instead",
            DeprecationWarning,
            stacklevel=2,
        )
        return CS_ARCH_AARCH64
    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

[wtdcode]

I see the issue, and unfortunately, pyproject.toml does not have the package renaming mechanism which cargo.toml supports. The only good way is to patch ropgadget but that is tedious and not feasible for every package.

Still, I feel like a better way is to handle such breakages in capstone releases instead of having two namespaces. Maybe we should explore some ways to automatically extract the API export difference?

[Rot127]

there is no deprecated mechanism in Capstone

That is definitely something we should add before we release the Beta. Fully agree and I am glad you brought it up. Opened #2851

Compatibility header like solution for Python

This is also something which was still on the todo list. I forgot to open an issue but added one now: #2852

I just forgot about it because I never used it. But the feature is already there:
https://github.com/capstone-engine/capstone/blob/next/docs/cs_v6_release_guide.md#python-binding-compatibility

Python packaging model limitations

As a general note: I understand your pain. In Rizin we have quite a lot of #if CS_API_MAJOR == 6 and before #if CS_API_MAJOR == 4/#if CS_API_MAJOR == 3 macros just to be compatible to more versions.

This version instability is something we want to fix with v6 (see https://github.com/capstone-engine/capstone/blob/next/docs/cs_v6_release_guide.md#overview).

That Python can't have two different package versions in the same environment is a Python problem though. And one of the reasons Python package management is famously messy.

I agree with @wtdcode that I don't see us spending the resources on a capstone6 package as workarounds for it. Currently at least, because we have too many other issues which need attention first.

Once we do a full v6 release, and deprecate v5, we could consider renaming. But then we should rename capstone -> capstone5 and give the v6 version the capstone name. Not the other way around.
Of course, if someone implements a "merge and forget" workflow for a capstone5 package + tests and all, I don't see a reason not to take it.

In the short/middle term

People won't get around updating Capstone to v6 at some point. There are so many improvements in the new version that even without the syntactic issue (like AArch64 renaming) it is unlikely to work well. The justifications for it are outlined in the release guide.

So I would suggest to:

• Implement Add deprecation mechanism #2851 as soon as possible. Should be done with the Beta release.
• Then Syntactic compatibility for Python bindings v5 -> v6 #2852 (also if possible with the Beta).
• If someone implements a full capstone5 workflow + tests, we can take it.
• Lastly, when we are in the processor of releasing the full v6 version, talk again about renaming the Python packages.

[Rot127]

@wtdcode

Maybe we should explore some ways to automatically extract the API export difference?

What do you have in mind?