A modern, async Python client library for interacting with Marzban VPN panel API.
- 🚀 Async/await support - Built with modern Python async patterns
- 📦 Modular design - Organized into logical sections for better maintainability
- 🔐 Type hints - Full type annotation for better IDE support
- ⚡ Simple & intuitive - Easy to use API interface
- 🛡️ Error handling - Comprehensive error handling with meaningful messages
- 📚 Well documented - Detailed documentation for all methods
Install using pip:
pip install marzbanapilibimport asyncio
from marzbanapilib import MarzbanAPI
async def main():
# Create API client using username and password
async with MarzbanAPI(
base_url="http://127.0.0.1:8000",
username="admin",
password="password"
) as api:
# Get system statistics
stats = await api.system.get_stats()
print(f"Total users: {stats['total_user']}")
# Create a new user
user = await api.user.create_user({
"username": "test_user",
"proxies": {"vmess": {}, "vless": {}},
"expire": 0, # No expiration
"data_limit": 0 # Unlimited
})
print(f"Created user: {user['username']}")
# Run the async function
asyncio.run(main())import asyncio
from marzbanapilib import MarzbanAPI
async def main():
# Use pre-existing access token (no username/password needed)
async with MarzbanAPI(
base_url="http://127.0.0.1:8000",
access_token="your_jwt_token_here"
) as api:
# Get system statistics
stats = await api.system.get_stats()
print(f"Total users: {stats['total_user']}")
asyncio.run(main())The library is organized into modular sections:
user- User management operationsadmin- Admin management operationssystem- System statistics and configurationcore- Xray core managementnode- Multi-node management
async with MarzbanAPI(...) as api:
# User operations
await api.user.create_user(...)
await api.user.get_users()
await api.user.reset_data_usage("username")
# System operations
await api.system.get_stats()
await api.system.get_inbounds()
# Core operations
await api.core.restart()
await api.core.get_config()
# Node operations
await api.node.get_all()
await api.node.create(...)# With username/password
api = MarzbanAPI("http://127.0.0.1:8000", "admin", "password")
await api.authenticate()
# Or with access token
api = MarzbanAPI("http://127.0.0.1:8000", access_token="your_jwt_token")
await api.authenticate()
# Use the API
users = await api.user.get_users()
# Don't forget to close
await api.close()from marzbanapilib import MarzbanAPI
async with MarzbanAPI(...) as api:
try:
user = await api.user.get_user("nonexistent")
except ValueError as e:
print(f"User not found: {e}")
except httpx.HTTPStatusError as e:
print(f"HTTP error: {e}")# Get active users with pagination
users = await api.user.get_users(
offset=0,
limit=50,
status="active",
sort="created_at"
)create_user(data)- Create new userget_user(username)- Get user detailsmodify_user(username, data)- Modify userdelete_user(username)- Delete userget_users(**filters)- List users with filtersreset_data_usage(username)- Reset user data usagerevoke_subscription(username)- Revoke user subscriptionget_usage(username)- Get user usage statistics- And more...
get_stats()- Get system statisticsget_inbounds()- Get inbound configurationsget_hosts()- Get proxy hostsmodify_hosts(data)- Modify proxy hosts
get_stats()- Get core statisticsrestart()- Restart Xray coreget_config()- Get core configurationmodify_config(data)- Modify core configuration
get_all()- List all nodescreate(data)- Create new nodeget(node_id)- Get node detailsmodify(node_id, data)- Modify nodedelete(node_id)- Delete nodereconnect(node_id)- Reconnect nodeget_usage()- Get nodes usage statistics
- Python 3.7+
- httpx
- pydantic
- aiofiles
This project is licensed under the MIT License - see the LICENSE file for details.
Contributions are welcome! Please feel free to submit a Pull Request.
For issues and feature requests, please use the GitHub issue tracker.