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 --passwordPX_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.
- Fork and clone the repository.
make installto set up the venv and pre-commit hooks.- Create a feature branch, make changes, add tests in
tests/. make check && make test— all checks must pass.- 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.