Skip to content

OpenStack Client Installation

The OpenStack Client (OSC) is a command-line client for OpenStack that unifies the command set for Compute, Identity, Image, Object Storage, and Block Storage APIs — and, through additional clients, Network, Orchestration, DNS, Key Management, Telemetry, and Placement — into a single shell with a consistent command structure.

This page describes how to install and configure the OSC.

Prerequisites

  • Basic knowledge of the Linux operating system (shell)
  • Access to a running Linux VM (Ubuntu in our example) with outbound HTTPS (TCP 443) access to the OpenStack API
  • Application Credentials and a matching clouds.yaml

Both regions

This sequence of commands applies to both regions; the region is selected in step 6 (Region 1 ch-zh1, Region 2 ch-ge1). Versions are pinned via the upper-constraints.txt from OpenStack 2025.1 (Epoxy).

1. Install uv

Install uv with the official uv installation script:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool update-shell

Restart your shell so the new PATH entry is picked up — or apply it to the current session with export PATH="$HOME/.local/bin:$PATH" — and verify:

uv --version

2. Load the constraints file

The release is OpenStack 2025.1 (Epoxy) — see the Epoxy release overview.

curl -fsSL https://opendev.org/openstack/requirements/raw/branch/stable/2025.1/upper-constraints.txt -o /tmp/upper-constraints-2025.1.txt

Tip

For repeated upgrades, keep the file in a permanent location (for example ~/.config/openstack/upper-constraints-2025.1.txt) and use that path in the commands below.

3. Install the client and the plugins

Existing installations

If openstack already exists (pipx, pip install --user), remove it first (pipx uninstall python-openstackclient) or let uv install with --force. Then start a new shell so the command points to the new binary.

uv tool install --python 3.12 \
  python-openstackclient \
  -c "/tmp/upper-constraints-2025.1.txt" \
  --with-executables-from gnocchiclient \
  --with-executables-from osc-placement \
  --with-executables-from python-barbicanclient \
  --with-executables-from python-cinderclient \
  --with-executables-from python-cloudkittyclient \
  --with-executables-from python-designateclient \
  --with-executables-from python-glanceclient \
  --with-executables-from python-heatclient \
  --with-executables-from python-keystoneclient \
  --with-executables-from python-mistralclient \
  --with-executables-from python-neutronclient \
  --with-executables-from python-novaclient \
  --with-executables-from python-octaviaclient \
  --with-executables-from python-swiftclient

Python 3.12 is used because OpenStack 2025.1 is tested against Python 3.9 to 3.12 and does not support Python 3.13 yet.

The packages passed via --with-executables-from provide the subcommands for Barbican, Cinder, CloudKitty, Designate, Glance, Heat, Keystone, Mistral, Neutron, Nova, Octavia, Swift, Gnocchi, and Placement.

All clients end up in one isolated uv tool environment — nothing is installed into the system Python.

No custom wheel required

Port forwarding is included in the 2025.1 client.

4. Set up bash completion

mkdir -p ~/.local/share/bash-completion/completions
openstack complete > ~/.local/share/bash-completion/completions/openstack

Restart your shell. Completion is loaded per user, so no sudo is needed.

Note

This completion is for bash and requires the bash-completion package (Ubuntu/Debian: sudo apt install bash-completion). zsh and fish are not covered — skip this step there.

5. Verify the installation

openstack --version  # prints the client version (7.x series for 2025.1)
uv tool list         # lists python-openstackclient with its service clients

6. Configure Application Credentials

mkdir -p ~/.config/openstack

# Paste your clouds.yaml content here, or create the file with:
vim ~/.config/openstack/clouds.yaml

# Only the owner may read the file, it contains the secret
chmod 600 ~/.config/openstack/clouds.yaml

# Define default connection and region
export OS_CLOUD=openstack
export OS_REGION_NAME=ch-zh1

Region 2

For ch-ge1 use export OS_REGION_NAME=ch-ge1, or select the openstack-ge1 entry with OS_CLOUD=openstack-ge1 (see the clouds.yaml example). OS_REGION_NAME overrides the region_name from the file.

To make the selection persistent across shells, append it to your ~/.bashrc:

echo 'export OS_CLOUD=openstack' >> ~/.bashrc
echo 'export OS_REGION_NAME=ch-zh1' >> ~/.bashrc
source ~/.bashrc

Note

OS_CLOUD=openstack refers to the configuration block in your clouds.yaml file; you may have multiple blocks. If you do not export the OS_CLOUD variable, you can specify the cloud configuration block directly in the command line. For example, openstack --os-cloud=openstack image list

Example: clouds.yaml

7. Test the configuration and connectivity

openstack image list --public

You should see a table with the columns ID, Name, and Status. The list depends on the region and the project, so it is not printed here.

Your OpenStack client is operational!

Updates

The tool environment is pinned via the constraints file. For the current patch level of the release, run the installation command from step 3 again with the same constraints file. Only use a new constraints file after a release upgrade.

uv tool upgrade is not needed for this and is not bound to the constraints file; uv tool upgrade --all would upgrade all tools installed with uv.

References