Install & Compatibility
Where this runs
tested against v0.30.3 · 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.95 runs
installs and imports cleanly · install 0.0s · import 1.994s · 54.2MB
glibcpy 3.10–3.95 runs
installs and imports cleanly · install 5.7s · import 1.868s · 53MB
50MB installed
● package 50MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Nextcloud
✓ from nc_py_api import Nextcloud
Main client for general interaction with a Nextcloud instance.
NextcloudApp
✓ from nc_py_api import NextcloudApp
✗ from nc_py_api import NextcloudApp; nc = NextcloudApp(url, auth)
NextcloudApp is primarily for developing applications *within* the Nextcloud ecosystem, where connection details are automatically provided. For standalone scripts or external clients, use `Nextcloud`.
This quickstart demonstrates how to connect to a Nextcloud instance using the `Nextcloud` client and retrieve information about the current user. It's recommended to use environment variables for sensitive credentials.
import os
from nc_py_api import Nextcloud
NEXTCLOUD_URL = os.environ.get('NEXTCLOUD_URL', 'https://nextcloud.example.com')
NEXTCLOUD_APP_PASS = os.environ.get('NEXTCLOUD_APP_PASS', 'your_app_password') # or username/password
if NEXTCLOUD_URL == 'https://nextcloud.example.com' or NEXTCLOUD_APP_PASS == 'your_app_password':
print("Please set NEXTCLOUD_URL and NEXTCLOUD_APP_PASS environment variables or replace placeholders.")
else:
try:
nc = Nextcloud(
nextcloud_url=NEXTCLOUD_URL,
nextcloud_app_pass=NEXTCLOUD_APP_PASS
)
current_user = nc.users.get_current_user()
print(f"Connected to Nextcloud as user: {current_user.user_id}")
print(f"Display name: {current_user.display_name}")
except Exception as e:
print(f"Failed to connect or fetch user info: {e}")
Debug
Known issues
breakingThe library switched its underlying HTTP client from `httpx` to `niquests`. If your code had deep integrations, custom client configurations, or relied on `httpx` specific exceptions/behavior, it might break.fixReview any custom HTTP client configurations or direct `httpx` usage. The public API should largely remain compatible, but internal changes can affect advanced use cases. Adjust error handling if `httpx` exceptions were caught directly.
affects: v0.21.0 and later
deprecatedThe `/apps/status/{appId}` endpoint for setting Nextcloud App status has been deprecated. The library now uses the `/ex-app/status` endpoint.fixIf you were manually interacting with Nextcloud's app status endpoints, switch to using the new `/ex-app/status` endpoint or rely on the `nc-py-api` methods which have been updated internally.
affects: v0.24.2 and later
gotchaWhen developing a Nextcloud App, use `NextcloudApp` which gets its context from Nextcloud. For standalone scripts or external clients, use `Nextcloud` and provide explicit connection details (URL, app password/username). Mixing these can lead to incorrect behavior or connection issues.fixEnsure you are using the correct class for your use case: `NextcloudApp` for in-app development, `Nextcloud` for external client scripts.
affects: All versions
gotchaError handling for external model downloads (e.g., in ExApps) has changed. If there's an error during a model download, an exception is now explicitly raised to prevent incorrect or partial ExApp installations.fixEnsure your code robustly handles exceptions during ExApp model installations or related operations. Previously, some errors might have been silently ignored or led to partial installs; now, explicit failure is indicated.
affects: v0.21.1 and later
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'nc_py_api'
The `nc-py-api` library is not installed in the Python environment, or there is a misspelling in the import statement.
fixInstall the library using pip: `pip install nc-py-api`
httpx.ConnectError: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate
This error occurs when the Nextcloud instance uses a self-signed SSL certificate or an untrusted certificate, and the Python client cannot verify it.
fixTo bypass SSL verification (for development/testing only, not recommended for production), initialize `Nextcloud` with `npa_nc_cert=False`: `nc = Nextcloud(nextcloud_url="https://your-nextcloud.com", npa_nc_cert=False, nc_auth_user="user", nc_auth_pass="password")`
nc_py_api._exceptions.NextcloudException: [401] Unauthorized
The provided authentication credentials (username/password or app token) are incorrect or do not have sufficient permissions to access the requested resource on the Nextcloud instance.
fixVerify that the `nextcloud_url`, `nc_auth_user`, and `nc_auth_pass` (or app token) are correct and that the user has the necessary permissions. Also, ensure the URL uses `https` if the Nextcloud instance requires it.
AttributeError: 'Nextcloud' object has no attribute 'some_sync_method_name'
Starting with `nc-py-api` version 0.30.0, many synchronous API wrappers are being deprecated in favor of asynchronous APIs. You are likely trying to call a synchronous method that has been removed or replaced in the `Nextcloud` (sync) client, or using an outdated code example.
fixMigrate your code to use the `AsyncNextcloud` class and its corresponding asynchronous methods with `await`, or consult the `nc-py-api` documentation for the current API structure. If a synchronous wrapper still exists for your method, ensure you are calling it correctly according to the current API.
nc_py_api.nextcloud_exception.NextcloudException: {"message":"Login failed. You have entered an incorrect username or password, or authentication has been disabled for this account."}
The provided Nextcloud URL, username, password, or app password is incorrect, or the user account is not active or improperly configured for API access.
fixVerify that the `nextcloud_url`, `nextcloud_user`, and `nextcloud_password` (or `nextcloud_app_pass`) parameters passed to `nc.nextcloud()` are correct and that the user has appropriate permissions.
Upgrade
Version history
0.30.3latest on PyPI · released Aug 11, 2026
Audit
Dependencies
No dependency data recorded yet.