Skip to content

Getting started

Install the OpenStack CLI

The OpenStack CLI, openstack, drives Breqwatr Cloud from a terminal. It's a Python package, installed with pip into a virtual environment, plus two plugins: one for load balancers and one for BKS.

What you install

Package Adds
python-openstackclient The openstack command: instances, volumes, networks, security groups, images and more
python-octaviaclient openstack loadbalancer commands
python-magnumclient openstack coe commands, used for BKS clusters

The CLI goes into a virtual environment: a folder with its own copy of Python and its own packages. It keeps the CLI apart from your operating system's Python, works the same way on Windows, macOS and Linux, and can be deleted cleanly. The steps are the same on every operating system except the command that activates the environment.

1. Get Python

On Windows and macOS, install Python 3.14. The CLI runs on newer releases too, but Ansible, used in the tutorials, doesn't yet run on Python 3.15. On Linux, use the Python your distribution ships.

From python.org/downloads/windows, download the installer for the latest Python 3.14 release, not 3.15, and run it. On the first screen, tick Add python.exe to PATH, then choose Install Now. In a new PowerShell window, python --version shows Python 3.14 followed by the release number.

From python.org/downloads/macos, download the installer for the latest Python 3.14 release, not 3.15, and run it. In a new Terminal window, python3.14 --version shows Python 3.14 followed by the release number.

Use the Python your distribution ships: Ubuntu 24.04 has 3.12, Debian 12 has 3.11 and AlmaLinux 9 has 3.9, all older than 3.15. On Debian and Ubuntu, add the venv module:

sudo apt install python3-venv

Red Hat Enterprise Linux, AlmaLinux and Rocky Linux include it.

2. Create the virtual environment

Open a new terminal, PowerShell on Windows, and create the environment in your home folder:

python -m venv $HOME\.openstack-cli

python3.14 -m venv ~/.openstack-cli

python3 -m venv ~/.openstack-cli

3. Activate it

This is the only step that differs between operating systems.

$HOME\.openstack-cli\Scripts\Activate.ps1

If PowerShell says running scripts is disabled on this system, allow local scripts for your account once, then activate again:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

source ~/.openstack-cli/bin/activate

source ~/.openstack-cli/bin/activate

The prompt now starts with (.openstack-cli). Don't go on until it does: if activation failed, pip installs into your system's Python instead of the environment.

4. Install the CLI

With the environment active, and the prompt starting with (.openstack-cli), the commands are the same on every operating system:

pip install python-openstackclient python-octaviaclient python-magnumclient
openstack --version

AlmaLinux 9 and other distributions based on Red Hat Enterprise Linux 9 ship Python 3.9, so pip installs an older release of the CLI there.

Each new terminal

The openstack command is available only while the environment is active. In each new terminal, run the activate command from step 3 first.

Check it reaches your project

The CLI reads its connection details from clouds.yaml, which you downloaded in Application credentials and clouds.yaml. Put it in the .config/openstack folder in your home folder:

Windows macOS and Linux
clouds.yaml location %USERPROFILE%\.config\openstack\clouds.yaml ~/.config/openstack/clouds.yaml

Then run a command against your project, and one for each plugin. Replace <cloud-name> with the name of the entry in your clouds.yaml; Application credentials and clouds.yaml shows where to find it.

openstack --os-cloud <cloud-name> server list
openstack --os-cloud <cloud-name> loadbalancer list
openstack --os-cloud <cloud-name> coe cluster list

Each one prints a table, or nothing if the project has none of that resource yet. An error means the CLI couldn't connect; see below.

If something goes wrong

Message What to check
openstack is not recognized, or command not found Activate the environment (step 3). The prompt starts with (.openstack-cli) when it's active
Running scripts is disabled on this system (Windows) Run the Set-ExecutionPolicy command in step 3, then activate again
Cloud <cloud-name> was not found clouds.yaml isn't in the folder above, or the name after --os-cloud doesn't match the entry in it
An authentication error The application credential has expired or been revoked. Create a new one and download a new clouds.yaml

Keeping it up to date

Activate the environment, then:

pip install --upgrade python-openstackclient python-octaviaclient python-magnumclient

Next

Quotas and your bill shows what your project can use and how usage is billed.

Further reading