Harbor API Client

0.26.2 verified Fri May 01 auth: no python

Async Python client for Harbor v2.0 API. Handles authentication, rate limiting, and all CRUD operations for Harbor registry resources (projects, repositories, artifacts, robots, users, etc.). Latest version 0.26.2, requires Python >=3.8. Actively maintained with monthly releases.

pip install harborapi

Common errors

error ImportError: cannot import name 'HarborClient' from 'harborapi' ↓

cause Older import path used 'from harborapi.client import HarborClient', but that module was restructured.

fix

Use 'from harborapi import HarborAsyncClient' (or HarborClient if sync, but sync is deprecated).

error harborapi.exceptions.Forbidden: Forbidden ↓

cause The authenticated user does not have the required permissions for the requested resource (e.g., admin privileges).

fix

Verify the user/robot has correct permissions in Harbor UI. Use an admin account or robot account with 'system_admin' role.

error httpx.ConnectError: [Errno 8] nodename nor servname provided, or not known ↓

cause The Harbor URL provided to the client is incorrect or the DNS cannot resolve the hostname.

fix

Check the URL (e.g., 'https://myharbor.example.com'). Ensure the host is reachable from your network.

Warnings

breaking Version 0.22.0+ drops Python 3.7 support. If you are on Python 3.7, pin harborapi<0.22.0. ↓

fix Update to Python >=3.8 or pin harborapi==0.21.0

breaking In version 0.20.0 the client factory function 'create_client' was removed. Use 'HarborAsyncClient' directly. ↓

fix Replace 'from harborapi import create_client' with 'from harborapi import HarborAsyncClient'

gotcha The client does not automatically refresh expired authentication tokens. You must catch '401' errors and re-authenticate. ↓

fix Wrap client calls with retry logic that re-calls login on 401.

deprecated Parameter 'verify_ssl' is deprecated in v0.25.0+ in favor of 'verify' (bool or SSLContext). ↓

fix Use 'verify=True' instead of 'verify_ssl=True'

Imports

HarborClient
wrong
```
from harborapi.client import HarborClient
```
correct
```
from harborapi import HarborClient
```
In older versions HarborClient was in a submodule. Now it's exposed at package level.
HarborAsyncClient
```
from harborapi import HarborAsyncClient
```
Primary client class for async usage.

Quickstart

Create an async client, authenticate with username/password, list projects.

import asyncio
from harborapi import HarborAsyncClient

async def main():
    client = HarborAsyncClient(
        url="https://your-harbor-instance.com",
        username="admin",
        password="password",  # or use secret
        verify=True
    )
    # List all projects
    projects = await client.get_projects()
    for project in projects:
        print(project.name)
    await client.close()

asyncio.run(main())