Cassandra no longer runs natively on Windows. Run it on a Windows machine with Docker Desktop or WSL2, verify the node with nodetool and cqlsh, and fix common startup errors.
Current versions of Apache Cassandra do not run natively on Windows. Windows support was removed in Cassandra 4.0, and the old DataStax MSI installer for Windows no longer exists. To run Cassandra on a Windows machine you run the Linux build, either in a Docker container or inside WSL2 (Windows Subsystem for Linux).
The quickest route, if you have Docker Desktop:
docker run --name cassandra -d -p 9042:9042 cassandra:5.0
Both routes are covered below. They are meant for development and testing. Production Cassandra clusters run on Linux servers.
Which option to choose
Docker Desktop
WSL2 with the Debian package
Setup effort
One command once Docker is installed
Install a Linux distribution, Java and the package
Best for
Trying Cassandra, throwaway test clusters, CI
A longer-lived local instance you manage like a Linux server
Upgrade
Pull a newer image
apt-get upgrade
Remove
Delete the container and volume
Purge the package
Docker Desktop on Windows itself uses WSL2 as its backend by default, so both options need WSL2 and hardware virtualisation enabled in the firmware.
Prerequisites
Windows 10 version 2004 or later, or Windows 11, 64-bit.
Virtualisation enabled in BIOS/UEFI.
Around 4 GB of memory free for the Linux VM. Cassandra is a Java server and sizes its heap from the memory it sees.
Option 1: Docker Desktop
Install Docker Desktop, start it, then open PowerShell:
docker run --name cassandra -d -p 9042:9042 -v cassandra_data:/var/lib/cassandra cassandra:5.0
-p 9042:9042 publishes the CQL port so that applications on Windows can connect to localhost:9042.
-v cassandra_data:/var/lib/cassandra keeps the data in a named volume, so it survives removing and recreating the container.
cassandra:5.0 is the official image for the 5.0 release line. Pin a version instead of using so that an image update does not surprise you with a major upgrade.
Cassandra takes up to a minute to start. Watch the log until a line like the one below shows that the CQL listener is up:
docker logs -f cassandra
Starting listening for CQL clients on /0.0.0.0:9042 (unencrypted)...
Press Ctrl+C to stop following the log, then open the CQL shell inside the container:
docker exec -it cassandra cqlsh
To stop and start the node later, use docker stop cassandra and docker start cassandra.
Option 2: WSL2 and the Cassandra Debian package
Install WSL2 and Ubuntu
Open PowerShell as Administrator:
wsl --install
This enables the required Windows features and installs Ubuntu. Restart when asked, then launch Ubuntu from the Start menu and create your Linux user. Confirm that the distribution is running under WSL version 2:
wsl -l -v
NAME STATE VERSION
* Ubuntu Running 2
Install Java
Cassandra 5.0 runs on Java 11 or Java 17. In the Ubuntu terminal:
The package creates a cassandra user, puts configuration in /etc/cassandra, data in /var/lib/cassandra and logs in /var/log/cassandra.
Start Cassandra
sudo service cassandra start
sudo service cassandra status
cqlsh needs Python 3, which Ubuntu already includes.
One difference from a real server: WSL shuts its VM down shortly after you close the last terminal, and it does not start with Windows. Cassandra stops with it. Keep an Ubuntu window open while you work, and run sudo service cassandra start again after a reboot.
Verify the installation
Check that the node is up. In WSL run the command directly; with Docker prefix it with docker exec -it cassandra:
UN means Up and Normal. The address, load and host ID will differ on your machine.
Then start cqlsh and write and read a row:
CREATE KEYSPACE demo
WITH replication = {'class': 'NetworkTopologyStrategy', 'datacenter1': 1};
CREATE TABLE demo.users (
user_id intPRIMARY KEY,
name text
);
INSERT INTO demo.users (user_id, name) VALUES (1, 'Asha');
SELECT*FROM demo.users;
user_id | name
---------+------
1 | Asha
(1 rows)
Type exit to leave the shell.
Connect from Windows applications
Point drivers and tools on the Windows side at localhost, port 9042. Docker publishes the port because of -p 9042:9042, and WSL2 forwards localhost connections from Windows into the Linux VM by default.
A default installation has authentication switched off: anyone who can reach the port has full access. That is acceptable on a development machine bound to localhost. Before exposing a node to a network, set authenticator: PasswordAuthenticator and authorizer: CassandraAuthorizer in cassandra.yaml, restart, and change the default cassandra superuser password.
Troubleshooting
Connection error: ('Unable to connect to any servers', {'127.0.0.1:9042': ConnectionRefusedError(111, ...)})
The node has not finished starting, or it has stopped. Wait until the log shows the "Starting listening for CQL clients" line. In WSL the log is /var/log/cassandra/system.log. If the process is gone, the end of that file says why.
The container exits after a few seconds, or docker ps -a shows exit code 137.
The Linux VM ran out of memory. Give WSL2 more memory by creating %UserProfile%\.wslconfig:
[wsl2]memory=6GB
Run wsl --shutdown in PowerShell and start Docker Desktop or Ubuntu again. For a small test node you can also cap the Cassandra heap on the container:
docker: Error response from daemon: Conflict. The container name "/cassandra" is already in use
A container with that name already exists. Start it with docker start cassandra, or remove it with docker rm cassandra first.
Bind for 0.0.0.0:9042 failed: port is already allocated
Something else is using port 9042, often a Cassandra instance in WSL while you start one in Docker. Stop one of them or publish a different host port, for example -p 9043:9042.
Cassandra will not start after a Java change.
Run java -version and check that it reports 11 or 17. Other versions are not supported by Cassandra 5.0.
Very slow disk performance in WSL.
Keep Cassandra's data in the Linux file system (the default /var/lib/cassandra). Paths under /mnt/c cross into the Windows file system and are much slower.
An old tutorial tells you to run cassandra.bat or install a DataStax MSI.
Those instructions apply to Cassandra 3.x and earlier. The Windows scripts were removed in 4.0, and the 3.x line is no longer maintained.
Understand what Apache Cassandra is, how its ring, replication and tunable consistency work, how to model tables in CQL, and when it is the wrong choice.
