tailscale

What it is and what it does

This package provides an async Python interface to the Tailscale API, letting you programmatically query device status, manage network configuration, and automate tailnet operations. It wraps HTTP calls to Tailscale's public API endpoints with typed dataclasses (Device, User, DNS settings, etc.) and exposes them through an async context manager. The client handles authentication via API key or OAuth, request timeouts, and JSON serialization using orjson for performance.

Typical use cases include Home Assistant integrations that trigger automations based on device connectivity, third-party tools that need to authorize or rename devices, and infrastructure scripts that manage subnet routes or DNS settings across a tailnet. An optional CLI is available for direct terminal access to the same operations without writing Python code.

Use it for:

• Home Assistant automations triggered by Tailscale device status changes or network events.
• Infrastructure scripts that authorize, rename, or delete devices from a tailnet programmatically.
• Third-party dashboards or monitoring tools that query device addresses, OS versions, and last-seen timestamps.
• DNS and subnet route management automation across multiple tailnet devices.
• Terminal-based CLI for quick device queries and tailnet administration without code.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Asynchronous Python client for querying and managing Tailscale networks programmatically via the Tailscale API, with optional command-line interface support.

Yes. The package is actively maintained, has no known vulnerabilities, low install friction, and a permissive MIT license. It is well-suited for anyone integrating Tailscale into Python automation, Home Assistant, or infrastructure tooling. Requires Python 3.11+ and a valid Tailscale API key; no other gotchas.

Install

tailscale on PyPI

pip install tailscale

uv add tailscale

poetry add tailscale

Installing tailscale

Before you install

Low install friction with a pure Python wheel. Actively maintained with recent releases; last commit 2026-08-14. Requires Python 3.11 or later. Four runtime dependencies (aiohttp, mashumaro, orjson, yarl) are all stable, widely-used async/serialization libraries.

License in practice

MIT license (permissive) allows use in commercial and private projects with minimal restrictions—only requires preserving copyright and license notices.

Quickstart

import asyncio
from tailscale import Tailscale

async def main():
    async with Tailscale(tailnet="your-tailnet", api_key="tskey-...") as ts:
        devices = await ts.devices()
        for device_id, device in devices.items():
            print(f"{device.hostname} ({device.os})")

asyncio.run(main())

Requires a valid Tailscale API key (tskey-...) issued by Tailscale and a tailnet name to authenticate.

Verify before relying

• Whether the optional CLI extra (tailscale[cli]) adds significant dependencies or install friction beyond the base package.
• Performance characteristics when managing large tailnets (number of devices, API call latency).
• Compatibility with Tailscale API versions and any breaking changes in recent Tailscale service updates.

Package facts

Evidence: tailscale-0.8.0-py3-none-any.whl

Keywords: api, async, client, home-assistant, mesh-vpn, network, tailnet, tailscale, vpn, wireguard

Tags

More Python Modules packages