{"id":3709,"library":"nacos-sdk-python","title":"Nacos Python SDK","description":"Python client for Nacos, a dynamic service discovery, configuration, and service management platform. It currently supports Nacos server versions 3.x and Python 3.10+. The library maintains a regular release cadence, with version 3.0.4 being the latest stable release.","status":"active","version":"3.0.4","language":"en","source_language":"en","source_url":"https://github.com/nacos-group/nacos-sdk-python","tags":["Nacos","service discovery","configuration management","cloud native","distributed systems"],"install":[{"cmd":"pip install nacos-sdk-python","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"This is the primary client for general configuration and naming services in a simplified manner.","symbol":"NacosClient","correct":"import nacos\nclient = nacos.NacosClient(...)"},{"note":"For explicit use of the Nacos V2 API for configuration management, especially with `ClientConfigBuilder` for advanced settings, import from `v2.nacos`. The direct `nacos.client` path for these V2-specific services might be incorrect or lead to older API versions.","wrong":"from nacos.client import NacosConfigService","symbol":"NacosConfigService","correct":"from v2.nacos import NacosConfigService, ClientConfigBuilder"},{"note":"For explicit use of the Nacos V2 API for naming and service discovery, import from `v2.nacos`.","symbol":"NacosNamingService","correct":"from v2.nacos import NacosNamingService, ClientConfigBuilder"}],"quickstart":{"code":"import os\nimport nacos\n\n# Configure Nacos server address and optional namespace/auth via environment variables\nSERVER_ADDRESSES = os.environ.get('NACOS_SERVER_ADDR', '127.0.0.1:8848')\nNAMESPACE_ID = os.environ.get('NACOS_NAMESPACE_ID', '') # e.g., 'public'\nACCESS_KEY = os.environ.get('NACOS_ACCESS_KEY', '')\nSECRET_KEY = os.environ.get('NACOS_SECRET_KEY', '')\n\n# Initialize Nacos Client\n# For production, ensure access_key and secret_key are provided for authentication.\nclient = nacos.NacosClient(\n    SERVER_ADDRESSES,\n    namespace=NAMESPACE_ID,\n    ak=ACCESS_KEY,\n    sk=SECRET_KEY\n)\n\n# --- Configuration Service Example ---\ndata_id = \"example_config\"\ngroup = \"DEFAULT_GROUP\"\n\n# Publish a configuration\nsuccess = client.publish_config(data_id, group, \"Hello from nacos-sdk-python!\")\nprint(f\"Published config: {success}\")\n\n# Get a configuration\nconfig_content = client.get_config(data_id, group)\nprint(f\"Retrieved config: {config_content}\")\n\n# --- Naming Service Example ---\nservice_name = \"example_service\"\nservice_ip = \"127.0.0.1\"\nservice_port = 8080\n\n# Register an instance\nregistered = client.add_naming_instance(service_name, service_ip, service_port)\nprint(f\"Registered service instance: {registered}\")\n\n# Query instances\ninstances = client.get_naming_instance(service_name, group_name=group)\nprint(f\"Discovered instances: {instances}\")\n\n# Deregister an instance\nderegistered = client.remove_naming_instance(service_name, service_ip, service_port)\nprint(f\"Deregistered service instance: {deregistered}\")\n","lang":"python","description":"This quickstart demonstrates how to initialize the `NacosClient` and perform basic configuration publishing/retrieval and service registration/discovery. It's recommended to configure Nacos server addresses, namespace, and authentication credentials via environment variables for flexible deployment. For Nacos server 3.x and above, ensure the Nacos server is running and accessible."},"warnings":[{"fix":"Ensure your Nacos server instance is running version 3.x or above when using `nacos-sdk-python` 3.x. Consult the Nacos official documentation for server upgrade guides.","message":"`nacos-sdk-python` 3.x clients are designed to be compatible with Nacos server 3.x and later. Older Nacos server versions (e.g., 0.x, 1.x, or 2.x) are generally not compatible with 3.x clients, and the Nacos server 3.2.0 removed legacy v1/v2 HTTP APIs.","severity":"breaking","affected_versions":"3.x"},{"fix":"Review the official documentation and migration guides for `nacos-sdk-python` 3.x to understand API changes, particularly when migrating from 2.x. Use `from v2.nacos import ...` for explicit V2 API interactions or advanced configurations like `ClientConfigBuilder`.","message":"The Nacos Python SDK 3.x introduced 'v2 API support', implying changes from previous API patterns, especially for configuration and service management. Direct imports from `nacos` vs. `v2.nacos` differentiate between simplified usage and explicit V2 API features.","severity":"breaking","affected_versions":"3.x"},{"fix":"Pass `ak` and `sk` parameters during `NacosClient` initialization, ideally sourced from secure environment variables or a secret management system. E.g., `client = nacos.NacosClient(..., ak=os.environ.get('NACOS_ACCESS_KEY'), sk=os.environ.get('NACOS_SECRET_KEY'))`.","message":"For production deployments, always configure `NacosClient` with `access_key` and `secret_key` (or `username`/`password`) for authentication with the Nacos server. Relying solely on a public namespace without authentication can lead to security vulnerabilities.","severity":"gotcha","affected_versions":"All"},{"fix":"If experiencing registration issues, verify that `nacos.server.contextPath` is set correctly on your Nacos server, or revert it to its default if custom paths are not strictly necessary.","message":"When configuring the Nacos server, modifying `nacos.server.contextPath` from its default value can sometimes cause service registration failures or other communication issues with the Python client.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}