---
id: mechanicalsoup
version: "1.4.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# MechanicalSoup — A Python library for automating interaction with websites

License: permissive · Maintenance: active · Downloads: 165.0K/mo

## What it is and what it does

MechanicalSoup is a Python library that automates interaction with websites by wrapping Requests (for HTTP) and BeautifulSoup (for HTML parsing) into a stateful browser interface. It handles the tedious parts of web automation: managing cookies across requests, following redirects, selecting and filling HTML forms, and navigating links. The library maintains session state automatically, so you can interact with a website as if you were a user clicking through pages and submitting forms.

It's designed for straightforward web scraping and automation tasks where the content is server-rendered HTML—not for sites that rely heavily on JavaScript to generate or modify content. The API is simple and intuitive: open a URL, select a form by CSS selector, fill in fields like a dictionary, and submit. It's a modern Python 3 successor to the older Mechanize library, actively maintained by a small team and tested against both CPython and PyPy3.

Use it for:

- Scrape search results or product listings from websites by automating form submission and following result links
- Automate login workflows and session-based data collection from sites requiring authentication
- Extract data from multi-page forms or workflows where you need to fill fields, submit, and parse results across requests
- Test web applications by simulating user interactions like form fills and navigation without a browser driver
- Monitor or archive web content by periodically fetching and parsing pages that require form interaction

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

MechanicalSoup automates interaction with websites by handling HTTP sessions, cookies, redirects, form submission, and link following—built on Requests and BeautifulSoup, but does not execute JavaScript.

Yes. MechanicalSoup is a solid choice for web automation and scraping when you need form submission and stateful interaction but don't require JavaScript execution. It has low install friction, active maintenance, no known vulnerabilities, and a permissive license. The five runtime dependencies are all widely used and stable. Install it if your target sites serve complete HTML and you want a lighter alternative to a full browser automation framework.

## Install

pip install mechanicalsoup
uv add mechanicalsoup
poetry add mechanicalsoup

## Installing MechanicalSoup

Before you install: Low friction: pure Python wheel with five common runtime dependencies (requests, beautifulsoup4, lxml, certifi, urllib3). Active maintenance since 2017 with recent commits; last release 441 days ago suggests stable, infrequent updates rather than abandonment.

License in practice: MIT license is permissive—you can use, modify, and distribute MechanicalSoup freely in commercial or private projects with minimal restrictions, only requiring attribution.

Quickstart:

pip install MechanicalSoup

import mechanicalsoup
browser = mechanicalsoup.StatefulBrowser()
browser.open("https://example.com")
browser.select_form()
browser["field"] = "value"
browser.submit_selected()

Requires Python 3.9 or later. Does not handle JavaScript-rendered content; pages must be fully formed in the initial HTML response.

Verify before relying:

- Performance characteristics with large-scale scraping or concurrent requests
- Compatibility with modern anti-scraping techniques or rate-limiting headers

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 165.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

web scraping with form submission, automated website interaction, cookie and redirect handling, web automation without javascript, html form filling and submission, stateful web browser automation, mechanize alternative python 3, web-scraping, form-automation, http-client

[View on SkillFed](https://skillfed.io/packages/mechanicalsoup) · [View on PyPI](https://pypi.org/project/mechanicalsoup/)