# pytest-socket

> Pytest Plugin to disable socket calls during tests

- **URL**: https://www.freshcrate.ai/projects/pytest-socket
- **Author**: Mike Fiedler
- **Category**: Frameworks
- **Latest version**: `0.8.0` (2026-05-21)
- **License**: MIT
- **Source**: https://github.com/miketheman/pytest-socket/issues
- **Homepage**: https://pypi.org/project/pytest-socket/
- **Language**: Python
- **GitHub**: 337 stars, 50 forks
- **Registry**: pypi (`pytest-socket`)
- **Tags**: `pypi`

## Description

# pytest-socket

[![PyPI current version](https://img.shields.io/pypi/v/pytest-socket.svg)](https://pypi.python.org/pypi/pytest-socket)
[![Python Support](https://img.shields.io/pypi/pyversions/pytest-socket.svg)](https://pypi.python.org/pypi/pytest-socket)
[![Tests](https://github.com/miketheman/pytest-socket/workflows/Python%20Tests/badge.svg)](https://github.com/miketheman/pytest-socket/actions?query=workflow%3A%22Python+Tests%22)
[![pre-commit.ci status](https://results.pre-commit.ci/badge/github/miketheman/pytest-socket/main.svg)](https://results.pre-commit.ci/latest/github/miketheman/pytest-socket/main)
[![Maintainability](https://api.codeclimate.com/v1/badges/1608a75b1c3a20211992/maintainability)](https://codeclimate.com/github/miketheman/pytest-socket/maintainability)
[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket.svg?type=shield)](https://app.fossa.io/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket?ref=badge_shield)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

A plugin to use with Pytest to disable or restrict `socket` calls during
tests to ensure network calls are prevented.

---

## Features

- Disables all network calls flowing through Python\'s `socket` interface.

## Requirements

- [Pytest](https://github.com/pytest-dev/pytest) 6.2.5 or greater

## Installation

You can install `pytest-socket` via [pip](https://pypi.python.org/pypi/pip/)
from [PyPI](https://pypi.python.org/pypi):

```console
pip install pytest-socket
```

or add to your `pyproject.toml` for [poetry](https://python-poetry.org/):

```ini
[tool.poetry.dev-dependencies]
pytest-socket = "*"
```

## Usage

Run `pytest --disable-socket`, tests should fail on any access to `socket` or
libraries using socket with a `SocketBlockedError`.

To add this flag as the default behavior, add this section to your
[`pytest.ini`](https://docs.pytest.org/en/6.2.x/customize.html#pytest-ini):

```ini
[pytest]
addopts = --disable-socket
```

or add this to your [`setup.cfg`](https://docs.pytest.org/en/6.2.x/customize.html#setup-cfg):

```ini
[tool:pytest]
addopts = --disable-socket
```

or update your [`conftest.py`](https://docs.pytest.org/en/6.2.x/writing_plugins.html#conftest-py-plugins) to include:

```python
from pytest_socket import disable_socket

def pytest_runtest_setup():
    disable_socket()
```

If you exceptionally want to enable socket for one particular execution
pass `--force-enable-socket`. It takes precedence over `--disable-socket`.

To enable Unix sockets during the test run (e.g. for async), add this option:

```ini
[pytest]
addopts = --disable-socket --allow-unix-socket
```

To enable specific tests use of `socket`, pass in the fixture to the test or
use a marker:

```python
def test_explicitly_enable_socket(socket_enabled):
    assert socket.socket(socket.AF_INET, socket.SOCK_STREAM)


@pytest.mark.enable_socket
def test_explicitly_enable_socket_with_mark():
    assert socket.socket(socket.AF_INET, socket.SOCK_STREAM)
```

To allow only specific hosts per-test:

```python
@pytest.mark.allow_hosts(['127.0.0.1'])
def test_explicitly_enable_socket_with_mark():
    assert socket.socket.connect(('127.0.0.1', 80))
```

or for whole test run

```ini
[pytest]
addopts = --allow-hosts=127.0.0.1,127.0.1.1
```

### Frequently Asked Questions

Q: Why is network access disabled in some of my tests but not others?

A: pytest's default fixture scope is "function", which `socket_enabled` uses.
If you create another fixture that creates a socket usage that has a "higher"
instantiation order, such as at the module/class/session, then the higher order
fixture will be resolved first, and won't be disabled during the tests.
Read more in [this excellent example](https://github.com/miketheman/pytest-socket/issues/45#issue-679835420)
and more about [pytest fixture order here](https://docs.pytest.org/en/stable/fixture.html#fixture-instantiation-order).

This behavior may change in the future, as we learn more about pytest
fixture order, and what users expect to happen.

## Contributing

Contributions are very welcome. Tests can be run with
[pytest](https://github.com/pytest-dev/pytest), please ensure the
coverage at least stays the same before you submit a pull request.

## License

Distributed under the terms of the
[MIT](http://opensource.org/licenses/MIT) license, "pytest-socket" is
free and open source software

[![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fmiketheman%2Fpytest-socket?ref=badge_large)

## Issues

If you encounter any problems, please [file an issue](https://github.com/miketheman/pytest-socket/issues)
along with a detailed description.

## References

This [Pytest](https://github.com/pytest-dev/pytest) plugin was generated with
[Cookiecutter](https://github.com/audreyr/cookiecutter) along with
[\

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `0.8.0` | 2026-05-21 | High | ## What's Changed  ### Enhancements  - Block DNS resolution (`getaddrinfo`, `gethostbyname`) when sockets are disabled #482 - Support CIDR network ranges in `allow_hosts` #479 - Warn before raising on a blocked socket call #468 - Cache hostname resolutions during a test run #369  ### Changes  - **Removed support for Python 3.8 and 3.9.** Python 3.10 is now the minimum. - Test against Python 3.13, 3.14, and free-threaded 3.13t/3.14t - Replaced Poetry with uv #429 - Added type hints |
| `0.7.0` | 2026-04-21 | Low | Imported from PyPI (0.7.0) |
| `0.6.0` | 2023-02-03 | Low | ## What's Changed * chore(deps): update dependency httpx to ^0.22.0 by @renovate in https://github.com/miketheman/pytest-socket/pull/113 * Add Change Log project URL by @scop in https://github.com/miketheman/pytest-socket/pull/115 * [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/miketheman/pytest-socket/pull/116 * chore(deps): update dependency pytest to v7 by @renovate in https://github.com/miketheman/pytest-socket/pull/117 * chore(deps): update actions/setup |
| `0.5.1` | 2022-01-23 | Low | ## What's Changed * [pre-commit.ci] pre-commit autoupdate by @pre-commit-ci in https://github.com/miketheman/pytest-socket/pull/104 * fix: don't break on doctests by @andreoliwa, @orf  in https://github.com/miketheman/pytest-socket/pull/109 * chore(deps): update dependency starlette to ^0.18.0 by @renovate in https://github.com/miketheman/pytest-socket/pull/110 * chore: update make target to handle installation by @miketheman in https://github.com/miketheman/pytest-socket/pull/111 * chore: |
| `0.5.0` | 2021-12-23 | Low | ## What's Changed * docs: Fix syntax for setup.cfg by @llimllib in https://github.com/miketheman/pytest-socket/pull/77 * chore(dev): update development commands by @miketheman in https://github.com/miketheman/pytest-socket/pull/83 * Fix pytest-socket raises IndexError with httpx by @ollipa in https://github.com/miketheman/pytest-socket/pull/85 * test: move the reenable fixture to conftest by @miketheman in https://github.com/miketheman/pytest-socket/pull/86 * Switch to poetry-core by @fabaf |
| `0.4.1` | 2021-08-28 | Low | Include tests and configs in source distribution archive #69  https://github.com/miketheman/pytest-socket/compare/0.4.0...0.4.1  ## What's Changed * pyproject.toml: include tests in sdist archive by @kwshi in https://github.com/miketheman/pytest-socket/pull/69  ## New Contributors * @kwshi made their first contribution in https://github.com/miketheman/pytest-socket/pull/69  **Full Changelog**: https://github.com/miketheman/pytest-socket/compare/0.4.0...0.4.1 |
| `0.4.0` | 2021-03-30 | Low | Enhancements:  * Enable Unix sockets selectively with --allow-unix-socket #54 * Test refactor, add CodeQL scanning * Correctly subclass socket.socket #50 * Add testing against Python 3.9, Dropped testing against Python 3.5 * Doc updates  https://github.com/miketheman/pytest-socket/compare/0.3.5...0.4.0  ## What's Changed * chore(deps): update dependency pytest to v6 by @renovate in https://github.com/miketheman/pytest-socket/pull/44 * Create codeql-analysis.yml by @miketheman in http |
| `0.3.5` | 2020-05-31 | Low | Bugfix release.  * Fix bug in marker evaluation #42 * Refactor tests for clarity  https://github.com/miketheman/pytest-socket/compare/0.3.4...0.3.5  https://pypi.org/project/pytest-socket/0.3.5/  # NOTE  This is the final release that supports Python 3.5 |
| `0.3.4` | 2020-04-10 | Low | Maintenance release.  * Drop support for unsupported versions of Python #23 * Convert toolchain from pip/tox/twine to poetry * Replace TravisCI and Appveyor with GitHub Actions #36 * Update for correct test output #31 * Add renovatebot for dependecy updates #26  https://github.com/miketheman/pytest-socket/compare/0.3.3...0.3.4  https://pypi.org/project/pytest-socket/0.3.4/ |
| `0.3.3` | 2019-02-09 | Low | * Fix hostname check when unicode on Python 2.7.x #22  https://github.com/miketheman/pytest-socket/compare/0.3.2...0.3.3  https://pypi.org/project/pytest-socket/0.3.3/ |

## Citation

- HTML: https://www.freshcrate.ai/projects/pytest-socket
- Markdown: https://www.freshcrate.ai/projects/pytest-socket.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/pytest-socket/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._