Apache Cassandra is a distributed NoSQL database designed for high availability and linear scalability. It handles large volumes of data across commodity servers without a single point of failure, making it ideal for applications that require fault tolerance, low-latency writes, and the ability to scale horizontally. Common use cases include time-series data storage, real-time analytics, messaging platforms, and any application where uptime and write performance are critical.
This guide walks through installing Apache Cassandra on Ubuntu using the official Apache Debian repository. By the end, you will have a working Cassandra installation with the cqlsh command-line client configured and a systemd-compatible init script for process management.
This guide supports Ubuntu 22.04 LTS, 24.04 LTS, and 26.04 LTS installations. The Apache Cassandra repository provides architecture-independent packages that work across all supported Ubuntu releases. Commands shown work identically on all supported LTS releases unless otherwise noted.
Cassandra requires at least 2GB of RAM to start with default settings. For production workloads, 8GB or more is recommended. If you are running on a memory-constrained system, you may need to adjust heap settings in
/etc/cassandra/cassandra-env.shafter installation.
Choose Your Cassandra Version
Apache Cassandra offers multiple release branches with different support timelines. The table below summarizes the available options to help you choose the right version for your deployment.
| Version | Status | Java Requirement | Best For |
|---|---|---|---|
| 5.0 | Latest GA (current) | Java 11 or 17 | New deployments wanting latest features |
| 4.1 | Previous stable | Java 8, 11, or 17 | Production systems needing proven stability |
| 4.0 | Older stable | Java 8, 11, or 17 | Legacy compatibility or specific version requirements |
For most new deployments, Cassandra 5.0 is recommended as it includes performance improvements, new features, and receives active development. This guide uses Cassandra 5.0 by default, but provides alternative repository configurations for 4.1 and 4.0 if you need them.
Update Ubuntu System Packages
Before installing Cassandra, update your system packages to ensure you have the latest security patches and dependency versions. This step helps prevent compatibility issues during installation.
sudo apt update && sudo apt upgrade -yInstall Java OpenJDK
Apache Cassandra is a Java application and requires a compatible Java Development Kit (JDK) to run. Cassandra 5.0 supports Java 11 or Java 17, while earlier versions also support Java 8. Install the headless variant to minimize disk usage on servers without graphical interfaces. For a detailed guide on Java installation, see our OpenJDK 17 installation guide for Ubuntu.
sudo apt install openjdk-17-jdk-headless -yVerify the installation by checking the Java version:
java -versionopenjdk version "17.0.17" 2025-10-21 OpenJDK Runtime Environment (build 17.0.17+10-Ubuntu-1) OpenJDK 64-Bit Server VM (build 17.0.17+10-Ubuntu-1, mixed mode, sharing)
Add the Apache Cassandra Repository
Apache provides official Debian packages through their repository. Add the repository configuration files to your system to enable package installation via APT. Choose the version that matches your requirements.
Import the GPG Key
Download and convert the Apache Cassandra signing keys to verify package authenticity:
curl -fsSL https://downloads.apache.org/cassandra/KEYS | sudo gpg --dearmor -o /etc/apt/keyrings/apache-cassandra.gpgCassandra 5.0 Repository (Recommended)
Create the repository configuration for the latest Cassandra 5.0 release using DEB822 format:
cat <<EOF | sudo tee /etc/apt/sources.list.d/cassandra.sources
Types: deb
URIs: https://debian.cassandra.apache.org
Suites: 50x
Components: main
Signed-By: /etc/apt/keyrings/apache-cassandra.gpg
EOFCassandra 4.1 Repository (Alternative)
If you need the previous stable release for compatibility reasons, use the 4.1 repository instead:
cat <<EOF | sudo tee /etc/apt/sources.list.d/cassandra.sources
Types: deb
URIs: https://debian.cassandra.apache.org
Suites: 41x
Components: main
Signed-By: /etc/apt/keyrings/apache-cassandra.gpg
EOFCassandra 4.0 Repository (Alternative)
For the older stable release, use the 4.0 repository:
cat <<EOF | sudo tee /etc/apt/sources.list.d/cassandra.sources
Types: deb
URIs: https://debian.cassandra.apache.org
Suites: 40x
Components: main
Signed-By: /etc/apt/keyrings/apache-cassandra.gpg
EOFInstall Apache Cassandra
With the repository configured, update the package cache and install the Cassandra package:
sudo apt update
sudo apt install cassandra -yThe package manager imports the GPG keys and resolves dependencies automatically. Verify the installed version:
cassandra -v5.0.6
Manage the Cassandra Service
The Cassandra Debian package includes an init script at /etc/init.d/cassandra that integrates with systemd through the LSB compatibility layer. This allows you to manage Cassandra using standard service commands.
Start and Enable the Cassandra Service
Start the Cassandra service:
sudo systemctl start cassandraCheck that the service is running correctly:
systemctl status cassandra● cassandra.service - LSB: distributed storage system for structured data
Loaded: loaded (/etc/init.d/cassandra; generated)
Active: active (running) since ...
Main PID: xxxxx (java)
...
Cassandra requires 30-60 seconds to fully initialize. The service status should show active (running) only after startup completes.
Enable automatic startup on boot:
sudo systemctl enable cassandraStop and Restart the Service
Stop the Cassandra service when needed:
sudo systemctl stop cassandraRestart the service to apply configuration changes:
sudo systemctl restart cassandraInstall the Cassandra Query Language Shell (cqlsh)
The Cassandra package includes a bundled cqlsh client, but it requires Python 3.6-3.11. Ubuntu 24.04 and 26.04 ship with Python 3.12 and 3.13 respectively, which causes the bundled cqlsh to fail with a compatibility error.
Ubuntu 22.04: Use the Bundled cqlsh
On Ubuntu 22.04, the bundled cqlsh works without modification because the system ships with Python 3.10. Verify it works:
cqlsh --versioncqlsh 6.2.0
Ubuntu 24.04 and 26.04: Install cqlsh via pip
On Ubuntu 24.04 and 26.04, install the standalone cqlsh package using Python’s pip package manager. This version includes the Cassandra Python driver and works with newer Python versions. For more details on pip usage, see our pip installation guide for Ubuntu.
Install Python pip if not already present:
sudo apt install python3-pip -yInstall cqlsh using pip:
sudo pip3 install --break-system-packages cqlshThe
--break-system-packagesflag is required on Ubuntu 24.04+ due to PEP 668, which protects the system Python environment. This is safe for standalone tools like cqlsh that don’t conflict with system packages. Alternatively, you can install cqlsh in a Python virtual environment to avoid this flag entirely.
Verify the pip-installed cqlsh version:
cqlsh --versioncqlsh 6.2.1
Connect to the Cassandra Database
Connect to the local Cassandra instance using cqlsh. Ensure the Cassandra service has fully started (wait at least 30 seconds after starting the service) before attempting to connect:
cqlshConnected to Test Cluster at 127.0.0.1:9042 [cqlsh 6.2.0 | Cassandra 5.0.6 | CQL spec 3.4.7 | Native protocol v5] Use HELP for help. cqlsh>
Type exit or press Ctrl+D to disconnect from the shell.
Configure Apache Cassandra
Cassandra stores its configuration files in /etc/cassandra/. The main configuration file is cassandra.yaml, which controls cluster settings, networking, storage paths, and performance parameters. Data is stored in /var/lib/cassandra/ and logs are written to /var/log/cassandra/.
By default, Cassandra listens on several ports: 9042 (CQL client connections), 7000 (inter-node cluster communication), and 7199 (JMX monitoring). On a single-node development setup, these ports are bound to localhost and pose minimal risk. For production deployments or multi-node clusters, configure UFW firewall rules to restrict access to trusted networks only.
JVM Configuration
For JVM-level adjustments such as heap size and garbage collection settings, edit the /etc/cassandra/cassandra-env.sh file. Add JVM arguments to the JVM_OPTS variable, which Cassandra reads at startup. Startup options like heap size can also be configured in /etc/default/cassandra. If you need to configure the JAVA_HOME environment variable for your system, see our Java environment path guide for Ubuntu.
Enable User Authentication
By default, Cassandra allows unauthenticated access, which is acceptable for development but should be changed for production deployments. Before modifying the configuration, create a backup:
sudo cp /etc/cassandra/cassandra.yaml /etc/cassandra/cassandra.yaml.backupOpen the configuration file for editing:
sudo nano /etc/cassandra/cassandra.yamlLocate and modify the following parameters to enable password authentication:
authenticator: org.apache.cassandra.auth.PasswordAuthenticator
authorizer: org.apache.cassandra.auth.CassandraAuthorizer
roles_validity_in_ms: 0
permissions_validity_in_ms: 0Setting the validity values to 0 disables caching of role and permission information, which is useful during initial setup. In production, you may want to increase these values to reduce authentication overhead.
Save the file and restart Cassandra to apply the changes:
sudo systemctl restart cassandraCreate an Administrative Superuser
After enabling authentication, the default credentials are cassandra / cassandra. Connect using these credentials:
cqlsh -u cassandra -p cassandraCreate a new superuser account. Replace admin and your_secure_password with your desired username and a strong password:
CREATE ROLE admin WITH PASSWORD = 'your_secure_password' AND SUPERUSER = true AND LOGIN = true;Exit the shell and reconnect with your new account:
cqlsh -u admin -p your_secure_passwordDisable the default cassandra account to prevent unauthorized access:
ALTER ROLE cassandra WITH PASSWORD = 'disabled_account' AND SUPERUSER = false AND LOGIN = false;
REVOKE ALL PERMISSIONS ON ALL KEYSPACES FROM cassandra;Grant full permissions to your new administrative account:
GRANT ALL PERMISSIONS ON ALL KEYSPACES TO admin;Configure Automatic Login
To avoid entering credentials each time you connect, configure a cqlshrc file. Create the directory and copy the sample configuration:
mkdir -p ~/.cassandra
sudo cp /etc/cassandra/cqlshrc.sample ~/.cassandra/cqlshrc
sudo chown $USER:$USER ~/.cassandra/cqlshrc
chmod 600 ~/.cassandra/cqlshrcEdit the file to add your credentials:
nano ~/.cassandra/cqlshrcLocate the [authentication] section and add your username and password:
[authentication]
username = admin
password = your_secure_passwordStoring passwords in plain text files carries security risks. Ensure the cqlshrc file has restrictive permissions (
chmod 600) and consider using environment variables or a secrets manager for production environments.
Rename the Cluster
The default cluster name is “Test Cluster,” which should be changed for production deployments. Update the system table:
cqlshUPDATE system.local SET cluster_name = 'Production Cluster' WHERE KEY = 'local';Exit cqlsh and update the cluster name in the cassandra.yaml configuration file:
sudo nano /etc/cassandra/cassandra.yamlFind the cluster_name setting near the top of the file and change it to match:
cluster_name: 'Production Cluster'Flush the system keyspace and restart Cassandra to apply the change:
nodetool flush system
sudo systemctl restart cassandraThe connection banner displays the new cluster name when you reconnect to cqlsh.
Update Apache Cassandra
Updates within the same minor version series (e.g., 5.0.5 to 5.0.6) are delivered through the configured repository and can be applied using standard APT commands:
sudo apt update
sudo apt install --only-upgrade cassandra -yAfter upgrading, restart the Cassandra service to load the new version:
sudo systemctl restart cassandraVerify the updated version:
cassandra -vFor major version upgrades (e.g., 4.1 to 5.0), consult the official Apache Cassandra documentation for migration procedures. Major upgrades may require data format migrations and configuration changes.
Remove Apache Cassandra
If you need to uninstall Cassandra from your system, follow these steps to remove the package and clean up associated files.
Stop and Disable the Service
Stop the Cassandra service and disable it from starting on boot:
sudo systemctl stop cassandra
sudo systemctl disable cassandraRemove the Cassandra Package
Uninstall the Cassandra package and remove unused dependencies:
sudo apt remove --purge cassandra -y
sudo apt autoremove -yRemove the Repository Configuration
Delete the repository configuration file and GPG key:
sudo rm -f /etc/apt/sources.list.d/cassandra.sources
sudo rm -f /etc/apt/keyrings/apache-cassandra.gpg
sudo apt updateRemove Data Directories (Optional)
The following commands permanently delete all Cassandra data, including databases, commit logs, and saved caches. Back up any important data before proceeding.
sudo rm -rf /var/lib/cassandra
sudo rm -rf /var/log/cassandra
sudo rm -rf /etc/cassandraIf you installed cqlsh via pip (Ubuntu 24.04 and 26.04), remove it as well:
sudo pip3 uninstall cqlsh cassandra-driver -yRemove any user-level cqlsh configuration files:
rm -rf ~/.cassandraVerify that Cassandra has been removed:
cassandra -vbash: cassandra: command not found
Confirm the package is no longer available from the repository:
apt-cache policy cassandraN: Unable to locate package cassandra
Troubleshooting
Cassandra Service Fails to Start
If the service fails to start, check the system logs for error messages:
journalctl -xeu cassandraCommon causes include insufficient memory (Cassandra requires at least 2GB RAM by default), incorrect file permissions on data directories, or Java version incompatibilities.
Connection Refused When Using cqlsh
If cqlsh reports “Connection refused,” ensure Cassandra has fully started. The service can take 30-60 seconds to initialize. Check the service status and wait for it to complete startup:
systemctl status cassandraYou can also monitor the Cassandra log file for startup progress:
tail -f /var/log/cassandra/system.logLook for a message containing “Startup complete” to confirm the service is ready to accept connections.
Bundled cqlsh Reports Unsupported Python Version
If you see “Warning: unsupported version of Python, required 3.6-3.11” when running cqlsh, the bundled client is incompatible with your Python version. On Ubuntu 24.04 and 26.04, install cqlsh via pip as shown in the installation section above. The pip-installed version (cqlsh 6.2.1) supports Python 3.12 and 3.13.
Port 9042 Already in Use
If Cassandra fails to start or cqlsh cannot connect, another service may be using port 9042. Check which process is using the port:
sudo lsof -i :9042If another Cassandra instance or service is running, stop it before starting Cassandra. If you need to run multiple instances, configure Cassandra to use a different port in /etc/cassandra/cassandra.yaml by modifying the native_transport_port setting.
Conclusion
You now have Apache Cassandra running on Ubuntu with a systemd-compatible init script, the cqlsh client for database interaction, and password authentication configured. From here, you can create keyspaces and tables, add nodes to form a cluster, or tune performance settings in cassandra.yaml. For production deployments, configure firewall rules for ports 9042 (CQL) and 7000 (inter-node) and schedule regular backups of your data directories.