---
title: Installation
description: Install openocd-python and its dependencies
---

import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';

openocd-python requires **Python 3.11 or later** and a working OpenOCD installation. The library itself has a single dependency: `cmsis-svd` for SVD register decoding.

## Install the package

<Tabs>
  <TabItem label="uv">
    ```bash
    uv add openocd-python
    ```
  </TabItem>
  <TabItem label="pip">
    ```bash
    pip install openocd-python
    ```
  </TabItem>
  <TabItem label="pipx (CLI only)">
    ```bash
    pipx install openocd-python
    ```
  </TabItem>
</Tabs>

The package installs both the Python library (`import openocd`) and a CLI tool (`openocd-python`).

## Dependencies

| Package | Version | Purpose |
|---------|---------|---------|
| `cmsis-svd` | >= 0.4 | SVD file parsing for peripheral register decoding |

No other Python dependencies are required. The library uses only the standard library for networking (`asyncio`), subprocess management, and data types.

## Install OpenOCD

openocd-python communicates with OpenOCD over its TCL RPC interface. You need OpenOCD installed and either already running or available on your `PATH` so the library can spawn it.

<Tabs>
  <TabItem label="Arch Linux">
    ```bash
    sudo pacman -S openocd
    ```
  </TabItem>
  <TabItem label="Debian / Ubuntu">
    ```bash
    sudo apt install openocd
    ```
  </TabItem>
  <TabItem label="macOS">
    ```bash
    brew install openocd
    ```
  </TabItem>
  <TabItem label="Windows">
    Download the latest release from [openocd.org](https://openocd.org/pages/getting-openocd.html) and add the `bin` directory to your system `PATH`.
  </TabItem>
  <TabItem label="From source">
    ```bash
    git clone https://github.com/openocd-org/openocd.git
    cd openocd
    ./bootstrap
    ./configure
    make
    sudo make install
    ```
  </TabItem>
</Tabs>

Verify OpenOCD is installed and accessible:

```bash
openocd --version
```

<Aside type="note">
openocd-python supports OpenOCD 0.11 and later. Some commands (like `adapter name`) require OpenOCD 0.12+. The library handles version differences automatically, falling back to older command variants when needed.
</Aside>

## Verify the installation

After installing both openocd-python and OpenOCD, run a quick check to confirm everything is working.

First, start OpenOCD with your target configuration. For example, with a CMSIS-DAP probe and an STM32F1 target:

```bash
openocd -f interface/cmsis-dap.cfg -f target/stm32f1x.cfg
```

Then, in another terminal, verify the Python package can connect:

```python
from openocd import Session

with Session.connect_sync() as ocd:
    state = ocd.target.state()
    print(f"Target: {state.name}, State: {state.state}")
```

You can also verify using the CLI:

```bash
openocd-python info
```

This prints the target name, state, transport, adapter, and clock speed.

<Aside type="tip">
If you get a `ConnectionError`, check that OpenOCD is running and that the TCL RPC port (default 6666) is not blocked by a firewall. The TCL RPC port is distinct from the GDB server port (3333) and the telnet port (4444).
</Aside>

## Development installation

To work on openocd-python itself, clone the repository and install the development dependencies:

```bash
git clone https://git.supported.systems/ryan/openocd-python.git
cd openocd-python
uv sync --extra dev
```

The `dev` extras include:

| Package | Purpose |
|---------|---------|
| `pytest` >= 8.0 | Test runner |
| `pytest-asyncio` >= 0.24 | Async test support |
| `ruff` >= 0.8 | Linter and formatter |

Run the test suite (no hardware needed -- all tests use a mock OpenOCD server):

```bash
uv run pytest
```

Run the linter:

```bash
uv run ruff check src/ tests/
```

## Next steps

- [First Connection](/getting-started/first-connection/) -- connect to OpenOCD and run your first command
- [Quick Start](/getting-started/quick-start/) -- complete working examples for common tasks
- [CLI Reference](/getting-started/cli/) -- use the `openocd-python` command-line tool