px-proxy 0.11.0

An HTTP proxy server to automatically authenticate through an NTLM proxy

Px

An HTTP(s) proxy server that allows applications to authenticate through an NTLM or Kerberos proxy server, typically used in corporate deployments, without having to deal with the actual handshake. Px leverages Windows SSPI or single sign-on and automatically authenticates using the currently logged in Windows user account. It is also possible to run Px on Windows, Linux and MacOS without single sign-on by configuring the domain, username and password to authenticate with.

Px uses libcurl and supports all the authentication mechanisms supported by libcurl.

Requires Python ≥ 3.10

Installation

pip install px-proxy
uv tool install px-proxy
pipx install px-proxy

On Windows, Winget and Scoop can also be used:

winget install genotrance.px
scoop install px

Prebuilt binaries and offline wheel packages are available on the releases page. See the installation guide for all options including Docker, WinSW, and source installs.

Quick start

# Run with an upstream proxy
px --proxy=proxyserver.com:8080

# Run with a PAC file
px --pac=http://example.com/proxy.pac

# Run with verbose logging
px --proxy=proxyserver.com:80 --verbose

# Save configuration to px.ini
px --proxy=proxyserver.com:8080 --save

# Test connectivity
px --test

Configuration

Px can be configured via command-line flags, environment variables (PX_*), dotenv files, or px.ini. See px --help for all options.

Common options:

Flag	Description
--proxy=HOST:PORT	Upstream proxy server(s), comma-separated
--pac=URL	PAC file URL or local path
--port=NUM	Listening port (default 3128)
--gateway	Allow remote clients
--hostonly	Restrict to local interfaces
--noproxy=LIST	Hosts/IPs that bypass the upstream proxy
--auth=TYPE	Force upstream auth type (ANY, NTLM, NEGOTIATE, BASIC, NONE)
--username=DOMAIN\user	Username for upstream proxy auth
--log=4	Log to stdout (verbose mode)

Full reference: Configuration

Credentials

If SSPI is not available, provide --username in domain\username format. The password is stored in the system keyring:

px --username=domain\username --password

PX_PASSWORD can be used as an alternative when keyring is not available.

See the usage guide for platform-specific keyring setup and client authentication.

Documentation

User guides
Installation	pip, wheels, binary, Docker, Winget, Scoop, WinSW, uninstallation
Usage	Credentials, client auth, examples, dependencies, limitations
Configuration	All CLI flags, environment variables, INI keys, auth types
Developer guides
Architecture	Runtime model, package layout, data flow, state management
Build	Build system, pyproject.toml, GitHub Actions, wheels, Nuitka, Docker
Testing	Test suite layout, running tests, fixtures, coverage
Reference
Changelog	Release history

Development

Requires uv.

git clone https://github.com/genotrance/px.git
cd px
make install
make test

Target	Description
make install	Create venv, install dependencies, install pre-commit hooks
make check	Run linters (ruff) and type checking (mypy)
make test	Run tests with coverage
make benchmark	Run concurrency benchmarks
make test-large-data	Run large data transfer reliability tests
make docker	Build local Docker images (full and mini)
make test-kerberos	Build KDC images and run Kerberos integration tests
make build	Build sdist and wheel
make clean	Remove build artifacts

Contributing

Bug reports and pull requests are welcome at https://github.com/genotrance/px/issues.

1. Fork and clone the repository.
2. make install to set up the venv and pre-commit hooks.
3. Create a feature branch, make changes, add tests in tests/.
4. make check && make test — all checks must pass.
5. Open a pull request.

Feedback

Px is definitely a work in progress and any feedback or suggestions are welcome. It is hosted on GitHub with an MIT license so issues, forks and PRs are most appreciated. Join us on the discussion board, Gitter or Matrix to chat about Px.

Credits

Thank you to all contributors for their PRs and all issue submitters.

Px is based on code from all over the internet and acknowledges innumerable sources.