Choreographer

1.2.1 · active · verified Thu Apr 09

Choreographer is a Python library by Plotly that enables remote control of browsers, primarily for generating static images from browser-based charting tools, but also supports other use cases. It acts as a DevTools Protocol implementation for Chrome-ish browsers, leveraging the user's local Chrome binary. Currently at version 1.2.1, it is actively developed with recent updates in late 2025.

Warnings

gotcha Choreographer is currently a work in progress and primarily supports Chrome-ish browsers. Support for other browsers is planned but not yet implemented.
Fix: Ensure you have a Chrome-compatible browser installed (e.g., Google Chrome, Microsoft Edge) and target it for automation. Be aware that non-Chrome browsers may not work as expected.
gotcha The library strongly recommends using `async/await` for asynchronous operations. While synchronous functions exist, they are intended as building blocks and might not be as efficient or robust for complex scenarios.
Fix: Adopt `async/await` patterns in your code for optimal performance and to leverage the full capabilities of the library.
gotcha Choreographer interacts with the Chrome binary on the user's machine. This means you need a local installation of a compatible browser for the library to function.
Fix: Verify that a Chrome-compatible browser is installed and accessible on the system where Choreographer is being run.

Install

pip install choreographer Install latest version

Imports

Browser

import choreographer as choreo
browser = await choreo.Browser()

Quickstart

This quickstart demonstrates how to launch a browser, create a new tab, navigate to a URL, and then close them using Choreographer with `asyncio`. It highlights the recommended asynchronous usage pattern. Ensure a Chrome-compatible browser (like Google Chrome or Microsoft Edge) is installed on your system for Choreographer to connect to.

import asyncio
import choreographer as choreo

async def main():
    # Launch a headless browser (default is headless=True)
    # To see the browser, use headless=False. Ensure a Chrome-compatible browser is installed.
    try:
        browser = await choreo.Browser(headless=True)
        print(f"Browser launched: {browser.url}")

        # Create a new tab
        new_tab = await browser.new_tab()
        print(f"New tab created: {new_tab.url}")

        # Navigate to a URL
        await new_tab.navigate("https://www.google.com")
        print(f"Navigated to: {await new_tab.get_url()}")

        # Wait for a few seconds to observe (optional)
        await asyncio.sleep(3)

        # Close the tab and then the browser
        await new_tab.close()
        await browser.close()
        print("Browser and tab closed successfully.")

    except Exception as e:
        print(f"An error occurred: {e}")

if __name__ == "__main__":
    asyncio.run(main())

view raw JSON →