Install & Compatibility
Where this runs
tested against v0.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 2.211s · 195.6MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 11.7s · import 2.094s · 188MB
196MB installed
● package 196MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
PEPHubClient
✓ from pephubclient import PEPHubClient
✗ from pephubclient.client import PEPHubClient
The primary client class is directly exposed at the top level of the package since version 0.5.0. Older versions might have required `from pephubclient.client import PEPHubClient`.
Initializes the PEPhub client and attempts to retrieve a public project. For private projects or authenticated actions, you would typically log in using an API key (e.g., from the `PH_KEY` environment variable).
import os
from pephubclient import PEPHubClient
# Initialize the client. The default host is https://pephub.databio.org
phc = PEPHubClient()
# Retrieve a publicly accessible project from PEPhub.
# 'test/test_project:test' is a common example project for testing.
try:
project = phc.get_project(namespace='test', name='test_project', tag='test')
print(f"Successfully retrieved project: {project.name}")
print(f"Project description: {project.description}")
print(f"Number of samples: {len(project.samples)}")
except Exception as e:
print(f"Error retrieving project 'test/test_project:test': {e}")
print("This project might not exist or might require authentication. ")
print("For private projects, set the PH_KEY environment variable and ")
print("then call `phc.login(api_key=os.environ.get('PH_KEY'))` before fetching.")
Errors
Common errors & fixes
requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: https://pephub.databio.org/api/v1/user/
Attempting to perform an authenticated action (e.g., list private projects, fetch a private project) without a valid API key or correct login.
fixSet the `PH_KEY` environment variable with your PEPhub API key and call `phc.login(api_key=os.environ.get('PH_KEY'))` before the authenticated action. pephubclient.exceptions.ProjectNotFoundException: Project 'your_namespace/your_project:your_tag' not found.
The specified project (namespace, name, and tag combination) does not exist on PEPhub or is not accessible to your user.
fixVerify the project details (namespace, name, tag). Ensure the project is public or that you are correctly authenticated and have permissions to access it. You can use `phc.list_namespaces()` and `phc.list_projects(namespace=...)` to inspect available projects.
ImportError: cannot import name 'PEPHubClient' from 'pephubclient' (<path_to_pephubclient/__init__.py>)
You might be using an older version of `pephubclient` where `PEPHubClient` was not directly exposed at the package root, or the library is not correctly installed.
fixUpgrade to the latest `pephubclient` (`pip install --upgrade pephubclient`). If the issue persists, try `from pephubclient.client import PEPHubClient` (though this is not the recommended path for current versions).
Upgrade
Version history
0.5.1latest on PyPI · released Mar 18, 2026
Audit
Dependencies
requestsrequiredHTTP client for API communication
logmuserequiredLogging utility
jsonschemarequiredJSON schema validation
peppyrequiredCore dependency for handling PEP objects locally
pydanticrequiredData validation and settings management
oauthlibrequiredOAuth implementation for authentication
requests-oauthlibrequiredOAuth client for Requests
richrequiredRich text and beautiful formatting in the terminal
python-joserequiredJSON Object Signing and Encryption for JWT handling
yacmanrequiredYet another configuration manager