ring-doorbell

Python Ring Door Bell is a library written for Python that exposes the Ring.com devices as Python objects.

There is also a command line interface that is work in progress. Contributors welcome.

Currently Ring.com does not provide an official API. The results of this project are merely from reverse engineering.

Documentation: http://python-ring-doorbell.readthedocs.io/

Installation

# Installing from PyPi
$ pip install ring_doorbell

# Installing latest development
$ pip install \
    git+https://github.com/python-ring-doorbell/python-ring-doorbell@master

Using the CLI

The CLI is work in progress and currently has the following commands:

Show your devices:
```
$ ring-doorbell
```
Or:
```
$ ring-doorbell show
```
List your device names (with device kind):
```
$ ring-doorbell list
```

Either count or download your vidoes or both:

$ ring-doorbell videos --count --download-all

Enable disable motion detection:

$ ring-doorbell motion-detection --device-name "DEVICENAME" --on
$ ring-doorbell motion-detection --device-name "DEVICENAME" --off

Listen for push notifications like the ones sent to your phone:
```
$ ring-doorbell listen
```
List your ring groups:
```
$ ring-doorbell groups
```

Show your ding history:

$ ring-doorbell history --device-name "Front Door"

Show your currently active dings:
```
$ ring-doorbell dings
```

See or manage your doorbell in-home chime settings:

$ ring-doorbell in-home-chime --device-name "Front Door"
$ ring-doorbell in-home-chime --device-name "Front Door" type Mechanical
$ ring-doorbell in-home-chime --device-name "Front Door" enabled True
$ ring-doorbell in-home-chime --device-name "Front Door" duration 5

Query a ring api url directly:

$ ring-doorbell raw-query --url /clients_api/dings/active

Run ring-doorbell --help or ring-doorbell <command> --help for full options

Using the API

The API has an async interface and a sync interface. All api calls starting async are asynchronous. This is the preferred method of interacting with the ring api and the sync versions are maintained for backwards compatability.

You cannot call sync api functions from inside a running event loop.

Initializing your Ring object

This code example is in the test.py file. For the deprecated sync example see test_sync.py.

import getpass
import asyncio
import json
from pathlib import Path

from ring_doorbell import Auth, AuthenticationError, Requires2FAError, Ring

user_agent = "YourProjectName-1.0"  # Change this
cache_file = Path(user_agent + ".token.cache")


def token_updated(token):
    cache_file.write_text(json.dumps(token))


def otp_callback():
    auth_code = input("2FA code: ")
    return auth_code


async def do_auth():
    username = input("Username: ")
    password = getpass.getpass("Password: ")
    auth = Auth(user_agent, None, token_updated)
    try:
        await auth.async_fetch_token(username, password)
    except Requires2FAError:
        await auth.async_fetch_token(username, password, otp_callback())
    return auth


async def main():
    if cache_file.is_file():  # auth token is cached
        auth = Auth(user_agent, json.loads(cache_file.read_text()), token_updated)
        ring = Ring(auth)
        try:
            await ring.async_create_session()  # auth token still valid
        except AuthenticationError:  # auth token has expired
            auth = await do_auth()
    else:
        auth = await do_auth()  # Get new auth token
        ring = Ring(auth)

    await ring.async_update_data()

    devices = ring.devices()
    pprint(devices.devices_combined)
    await auth.async_close()


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

Event Listener

event_listener = RingEventListener(ring, credentials, credentials_updated_callback)
event_listener.add_notification_callback(_event_handler(ring).on_event)
await event_listener.start()

Listing devices linked to your account

# All devices
devices = ring.devices()
{'chimes': [<RingChime: Downstairs>],
'doorbots': [<RingDoorBell: Front Door>]}

# All doorbells
doorbells = devices['doorbots']
[<RingDoorBell: Front Door>]

# All chimes
chimes = devices['chimes']
[<RingChime: Downstairs>]

# All stickup cams
stickup_cams = devices['stickup_cams']
[<RingStickUpCam: Driveway>]

Playing with the attributes and functions

devices = ring.devices()
for dev in list(devices['stickup_cams'] + devices['chimes'] + devices['doorbots']):
    await dev.async_update_health_data()
    print('Address:    %s' % dev.address)
    print('Family:     %s' % dev.family)
    print('ID:         %s' % dev.id)
    print('Name:       %s' % dev.name)
    print('Timezone:   %s' % dev.timezone)
    print('Wifi Name:  %s' % dev.wifi_name)
    print('Wifi RSSI:  %s' % dev.wifi_signal_strength)

    # setting dev volume
    print('Volume:     %s' % dev.volume)
    await dev.async_set_volume(5)
    print('Volume:     %s' % dev.volume)

    # play dev test shound
    if dev.family == 'chimes':
        await dev.async_test_sound(kind = 'ding')
        await dev.async_test_sound(kind = 'motion')

    # turn on lights on floodlight cam
    if dev.family == 'stickup_cams' and dev.lights:
        await dev.async_lights('on')

Showing door bell events

devices = ring.devices()
for doorbell in devices['doorbots']:

    # listing the last 15 events of any kind
    for event in await doorbell.async_history(limit=15):
        print('ID:       %s' % event['id'])
        print('Kind:     %s' % event['kind'])
        print('Answered: %s' % event['answered'])
        print('When:     %s' % event['created_at'])
        print('--' * 50)

    # get a event list only the triggered by motion
    events = await doorbell.async_history(kind='motion')

Downloading the last video triggered by a ding or motion event

devices = ring.devices()
doorbell = devices['doorbots'][0]
await doorbell.async_recording_download(
    await doorbell.async_history(limit=100, kind='ding')[0]['id'],
                     filename='last_ding.mp4',
                     override=True)

Displaying the last video capture URL

print(await doorbell.async_recording_url(await doorbell.async_last_recording_id()))
'https://ring-transcoded-videos.s3.amazonaws.com/99999999.mp4?X-Amz-Expires=3600&X-Amz-Date=20170313T232537Z&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=TOKEN_SECRET/us-east-1/s3/aws4_request&X-Amz-SignedHeaders=host&X-Amz-Signature=secret'

Controlling a Light Group

groups = ring.groups()
group = groups['the-group-you-want']

print(group.lights)
# Prints True if lights are on, False if off

# Turn on lights indefinitely
await group.async_set_lights(True)

# Turn off lights
await group.async_set_lights(False)

# Turn on lights for 30 seconds
await group.async_set_lights(True, 30)

How to contribute

See our Contributing Page.

Credits && Thanks

This project was inspired and based on https://github.com/jeroenmoors/php-ring-api. Many thanks @jeroenmoors.
A guy named MadBagger at Prism19 for his initial research (http://www.prism19.com/doorbot/second-pass-and-comm-reversing/)
The creators of mitmproxy (https://mitmproxy.org/) great http and https traffic inspector
@mfussenegger for his post on mitmproxy and virtualbox https://zignar.net/2015/12/31/sniffing-vbox-traffic-mitmproxy/
To the project http://www.android-x86.org/ which allowed me to install Android on KVM.
Many thanks to Carles Pina I Estany <carles@pina.cat> for creating the python-ring-doorbell Debian Package (https://tracker.debian.org/pkg/python-ring-doorbell).

Release files for ring-doorbell 0.9.14

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ring-doorbell 0.9.14
File	Size	Uploaded
ring_doorbell-0.9.14.tar.gz	68.1 kB	Feb 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for ring-doorbell 0.9.14
File	Interpreter	ABI	Platform	Reset
ring_doorbell-0.9.14-py3-none-any.whl 50.3 kB Feb 28, 2026	Python 3	none	any	Details

Total release size: 118.3 kB

Release files / ring_doorbell-0.9.14.tar.gz

Download URL	ring_doorbell-0.9.14.tar.gz
Size	68.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`33df67c0cba8d0ece2b89a4dcee6602baf47b44fbfc1b3a085e8a3d54c016917`
BLAKE2b-256 checksum How to use checksums	`6c4eee8bc785b04a8d64ffb9fcf4ddfededc94d78ca2a9ed0d13af29413b54f2`
Upload date	Feb 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/python-ring-doorbell/python-ring-doorbell
Publishing commit: github.com/python-ring-doorbell/python-ring-doorbell/tree/28fd01c47130350614d555b3b4e360aa9a9e4c71

Workflow

Publishing configuration: github.com/python-ring-doorbell/python-ring-doorbell/blob/28fd01c47130350614d555b3b4e360aa9a9e4c71/.github/workflows/publish.yml
Publishing logs: github.com/python-ring-doorbell/python-ring-doorbell/actions/runs/22522384449/attempts/1

Artifact

Subject: ring_doorbell-0.9.14.tar.gz
SHA-256 checksum: 33df67c0cba8d0ece2b89a4dcee6602baf47b44fbfc1b3a085e8a3d54c016917 Verifying attestations

Release files / ring_doorbell-0.9.14-py3-none-any.whl

Download URL	ring_doorbell-0.9.14-py3-none-any.whl
Size	50.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5b3b3ebffcdaa1bc50f137a09062f36da42e3e59a63fe134292e16275142d9ec`
BLAKE2b-256 checksum How to use checksums	`39c069d6064b6b294ff4ffea85da845e90d99aae8b7515d6d6b0c342a9ea1d60`
Upload date	Feb 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/python-ring-doorbell/python-ring-doorbell
Publishing commit: github.com/python-ring-doorbell/python-ring-doorbell/tree/28fd01c47130350614d555b3b4e360aa9a9e4c71

Workflow

Publishing configuration: github.com/python-ring-doorbell/python-ring-doorbell/blob/28fd01c47130350614d555b3b4e360aa9a9e4c71/.github/workflows/publish.yml
Publishing logs: github.com/python-ring-doorbell/python-ring-doorbell/actions/runs/22522384449/attempts/1

Artifact

Subject: ring_doorbell-0.9.14-py3-none-any.whl
SHA-256 checksum: 5b3b3ebffcdaa1bc50f137a09062f36da42e3e59a63fe134292e16275142d9ec Verifying attestations