tiktokpy: driving TikTok through a Playwright browser session

A browser wrapper, not a documented API client

TikTokPy is a Python library whose stated purpose is automated TikTok interactions. The description in the package metadata is plain: tool for automated TikTok interactions, with keywords that include tiktok, bot, wrapper, webapi and marketing, and a repository topic list that mixes tiktok-api with tiktok-scraper. What sits underneath the wrapper is Playwright, the browser automation library, together with playwright-stealth, which the dependency list includes as a direct requirement. That combination explains nearly every design choice in the project. There is no signed request, no token exchange and no documented endpoint in the README, because the library operates the same web interface a person uses, driving a real browser through an authenticated session. The intended audience fields in the metadata list Science/Research, Information Technology and End Users/Desktop, and the development status classifier says Alpha, which is the first thing a reader should weigh.

Cookies and settings.toml are the session state

The run procedure is two steps. The first is python quicklogin.py, which the README says creates your cookies and settings.toml file, and the second is python quickstart.py once you have logged in. That is the whole authentication model, and it is worth being explicit about what it means: a browser session is written to disk, and the library talks to TikTok through the cookies that session produced rather than through a credential you hand to a server. Anyone evaluating this for a shared or automated environment has to think about where those files live and who can read them, because the README says nothing about encrypting them or excluding them from version control, and the repository does contain a .gitignore whose contents are not shown. The library exposes an asynchronous context manager, so a session is opened and closed inside an async with block rather than through a constructor that leaves state dangling.

A small object model over trending, feed and follow actions

The public surface visible in the quickstart is compact. Two read methods return lists of items: trending takes an amount argument, and user_feed takes a username and an amount argument. Four write methods take an item or a username: like, unlike, follow and unfollow, where follow and unfollow are given the value of item.author.username. What the returned items carry is where the object model gets interesting. An item exposes a music attribute with a title, a challenges attribute holding tags whose own title attribute is readable, and a stats attribute with comments, plays, shares and likes. The shape is a small typed model over what the browser response contained, and the library uses pydantic for it, with the dependency pinned to the 1.x series. The typing is what makes a scraping library usable in a script without a pile of dictionary lookups, and it is also what makes a pydantic major version change a potentially breaking event for anyone building on these objects.

Installing tiktokpy and running the quickstart

The README gives a plain pip install, and it gives a second step that is easy to miss because it is about the browser rather than the package:

pip install tiktokpy

playwright install firefox

The second command downloads the browser binary that the library drives, and Firefox is the browser named in the project documentation. After that, the intended sequence is to create the session and then run the example, and the quickstart file is short enough to read in full before you execute it:

async def main():
    async with TikTokPy() as bot:
        trending_items = await bot.trending(amount=5)

The feed read follows the same pattern, taking the account name as a keyword argument and an amount:

        user_feed_items = await bot.user_feed(username="tiktok", amount=5)

What you should see when it works is the printed metadata described in the example, the music title, the challenge tags and the statistics counters for comments, plays, shares and likes. If the session files are missing, the login step has not been done yet, and if the browser is missing, the playwright install step has not been done.

Dependencies that anchor the library to an older Python ecosystem

The dependency list is where the project's age shows. The Python constraint is ^3.8, the classifier for the environment is Console, and pydantic is held at ^1.6.1, which is the older major series. The build backend is Poetry, requiring poetry>=0.12 with the masonry backend, and the repository carries a poetry.lock, a setup.cfg and a .pre-commit-config.yaml alongside the source. The dev dependency set is unusually complete for a library of this size: pytest with pytest-cov, pytest-mock and pytest-asyncio, black and isort for formatting, ruff, pylint, mypy, bump2version and pre-commit. Formatting is configured with a black line-length of 100 and an isort profile of black, and there is a Dockerfile.test in the repository root, so containerised test runs are part of the intended workflow. Optional functionality is handled through an extra: parsel is marked optional and exposed as the html extra, which suggests HTML parsing is a separate path from the JSON-shaped responses the object model mostly deals with.

No tagged releases and an alpha status classifier

Maintenance facts for this project are thin, and stating them plainly is more useful than inferring a rhythm that the repository does not show. The last push to the repository was on 2026-10-19, and the repository is not archived, so work is clearly happening at the source level. The repository has no GitHub releases, so there is no published changelog to read and no version history to diff against. The version in the package metadata is 0.9.4, and the classifier describes the project as Development Status :: 3 - Alpha. A 0.x version with an alpha label tells you the author does not consider the interface settled, which for a scraping library is an honest warning about the shape of the returned objects. Licensing is straightforward: the metadata records MIT, the repository root contains a LICENSE file, and the pyproject includes it in the distribution. The project is distributed under the MIT terms, which allow reuse and modification with the notice retained, though anyone with an organisation specific policy should read the LICENSE file rather than take that summary as advice.

Where a Playwright driven library stops being the right tool

The obvious failure mode is platform level, not code level. Driving a browser against a consumer social product is the kind of automation that platforms detect and restrict, and the dependency list including playwright-stealth indicates an intent to make the session less obviously automated. The README documents no rate limits, no retry or backoff policy, no account safety guidance and no proxy configuration, so a script that loops over trending items calling like and follow in quick succession has no documented guard rails from the library side. If your requirement is measured reporting or marketing analytics, a browser library that returns parsed objects without a stability promise is the wrong foundation, and if a session account matters to you, the risk is not something the project takes on. The alternative approach is to drive Playwright yourself and keep the session and the extraction logic in your own code, which is more work but leaves the selectors, the pacing and the account handling under your control instead of behind a 0.9.4 alpha wrapper.

Editorial conclusion

tiktokpy is worth a try for a researcher, a data collection experiment or a personal automation that already accepts the risk of automating a consumer platform, and the Playwright based design explains why it can read feed content that a request only client would miss. It is the wrong choice for anything with a service level agreement, for marketing reporting that needs a stable schema, and for any account whose safety you care about, because the README documents no rate limiting, no retry policy and no account safety guidance. Before you run it, read quicklogin.py and settings.toml to see what session state it writes to disk, and check the pydantic version floor in pyproject.toml, since the library is pinned to the 1.x line.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. sudoguy/tiktokpy on GitHub