Fixing Cqlsh Python Version Error on MacOS

If you’re encountering the following error when starting cqlsh on a macOS system, this post is for you.

Warning: unsupported version of Python, required 3.6-3.11 but found 3.12
No appropriate Python interpreter found.

This error can be a little confusing because it doesn’t specify the maximum usable Python version. If we look in bin/cqlsh we’ll find something like this:

# test whether a version string matches one of the supported versions for cqlsh
is_supported_version() {
    version=$1
    major_version="${version%.*}"
    minor_version="${version#*.}"
    # python 3.8-3.11 are supported
    if [ "$major_version" = 3 ] && [ "$minor_version" -ge 8 ] && [ "$minor_version" -le 11 ]; then
        echo "supported"
    # python 3.6-3.7 are deprecated
    elif [ "$major_version" = 3 ] && [ "$minor_version" -ge 6 ] && [ "$minor_version" -le 7 ]; then
        echo "deprecated"
    else
        echo "unsupported"
    fi
}

This issue typically arises when you have an incompatible Python version installed via homebrew. Fortunately, there are straightforward steps to resolve this.

Checking Your Python Versions

Before making any changes, check which Python version is being used by default. In your terminal run which python3 to find out the Python version used by default, then call it with the --version flag. Here’s an example:

$ which python3
/opt/homebrew/bin/python3
$ python3 --version
Python 3.12.4

You can find all the python3 executables in your path by adding the -a switch:

$ which -a python3
/opt/homebrew/bin/python3
/usr/bin/python3

You can check the system python version by specifying the full path:

$ /usr/bin/python3 --version
Python 3.9.6

Specifying the Correct Python Version for cqlsh

If you have an appropriate version of Python (between 3.6 and 3.11) installed but not being used by default, you can explicitly tell cqlsh to use this version. For example, if /usr/bin/python3 is a compatible version, you can set it for cqlsh as follows:

export USER_SPECIFIED_PYTHON=/usr/bin/python3

Run the above command in your terminal before starting cqlsh, and it should resolve the error:

bin/cqlsh
Connected to Test Cluster at 127.0.0.1:9042
[cqlsh 6.3.0 | Cassandra 5.1-SNAPSHOT | CQL spec 3.4.8 | Native protocol v5]
Use HELP for help.
cqlsh>

Permanent Solution

For a more permanent solution, you can add the export command to your shell’s startup file (.bash_profile, .zshrc, etc.). Open the file in a text editor and add:

export USER_SPECIFIED_PYTHON=/usr/bin/python3

Save the file and reload your shell configuration:

source ~/.bash_profile
# or
source ~/.zshrc

Conclusion

By specifying the appropriate Python version using USER_SPECIFIED_PYTHON you can have multiple versions of Python on your machine and ensure cqlsh uses one that’s compatible.

If you found this post helpful, please consider sharing to your network. I'm also available to help you be successful with your distributed systems! Please reach out if you're interested in working with me, and I'll be happy to schedule a free one-hour consultation.