From 20baddf546c8f3a541f4471a0f4f74bc121bfa6c Mon Sep 17 00:00:00 2001 From: Loren Eteval Date: Fri, 28 Aug 2026 20:32:33 +0800 Subject: [PATCH] Rewrite PyPI installation guide Signed-off-by: Loren Eteval --- Install-From-PyPI.md | 203 ++++++++++++++++++++++++++++++++----------- 1 file changed, 151 insertions(+), 52 deletions(-) diff --git a/Install-From-PyPI.md b/Install-From-PyPI.md index f2c976b..c33f826 100644 --- a/Install-From-PyPI.md +++ b/Install-From-PyPI.md @@ -1,67 +1,166 @@ -> [!WARNING] -> This topic is only recommended for **experienced users** +# Install From PyPI ---- +Furious is published on PyPI as [`Furious-GUI`](https://pypi.org/project/Furious-GUI/). A normal installation also +installs PySide6 and the supported native core bindings automatically; the GUI and cores do not need to be installed +separately. > [!NOTE] -> If installed via `pip`, the application will run on native Python. Requires Python 3.8 and above. +> Supported binary wheels already contain the compiled native components. Most users do **not** need Go, CMake, GCC, +> Clang, MinGW, or another compiler toolchain. -# Install +## Install -You have to install GUI and core ***seperatedly*** from PyPI. +A virtual environment is recommended so Furious and its dependencies remain isolated, but it is not required. -## Install GUI +Create a virtual environment: -> [!NOTE] -> Install Furious in a Python virtual environment(i.e. venv) is recommended. - -> [!NOTE] -> Furious supports **minimum PySide6 version 6.1.0** since **version 0.2.11**. - -``` -pip install Furious-GUI +```bash +python -m venv .venv ``` -## Install Core +Activate it on Windows PowerShell: -### Core Building Tools - -> [!NOTE] -> These steps are the same in [Xray-core-python](https://github.com/LorenEteval/Xray-core-python) -> or [hysteria2-python](https://github.com/LorenEteval/hysteria2-python) *Core Building Tools* steps. - -> [!NOTE] -> Please pay extra attention that upstream projects are dropping build support on go 1.20.x - -To install Furious via `pip` you must have tools ready for building these bindings for your current platform first. Core building requires: - -* [go](https://go.dev/doc/install) in your PATH. go 1.20.0 and above is recommended. To check go is ready, - type `go version`. Also, if google service is blocked in your region(such as Mainland China), you have to configure - your GOPROXY to be able to pull go packages. For Chinese users, refer to [goproxy.cn](https://goproxy.cn/) for more - information. -* [cmake](https://cmake.org/download/) in your PATH. To check cmake is ready, type `cmake --version`. -* A working GNU C++ compiler(i.e. GNU C++ toolchains). To check GNU C++ compiler is ready, type `g++ --version`. These - tools should have been installed in Linux or macOS by default. If you don't have GNU C++ toolchains(especially for - Windows users) anyway: - - * For Linux users: type `sudo apt update && sudo apt install g++` and that should work out fine. - * For Windows users: install [MinGW-w64](https://sourceforge.net/projects/mingw-w64/files/mingw-w64/) - or [Cygwin](https://www.cygwin.com/) and make sure you have add them to PATH. - -> [!NOTE] -> Supported cores(shipped as Python binding): -> * `Xray-core` -> * `hysteria`(go1.20 only) -> * `hysteria2` -> * `tun2socks` - -e.g. -``` -pip install Xray-core +```powershell +.\.venv\Scripts\Activate.ps1 ``` -# Launch GUI +Or on Linux and macOS: +```bash +source .venv/bin/activate ``` + +Upgrade pip and install Furious: + +```bash +python -m pip install --upgrade pip +python -m pip install Furious-GUI +``` + +Launch the application: + +```bash Furious -``` \ No newline at end of file +``` + +You can also launch the installed package directly: + +```bash +python -m Furious +``` + +## What pip Installs + +`Furious-GUI` declares its runtime dependencies directly. The installation includes: + +* `PySide6-Essentials` and `PySide6-Addons` for the GUI; +* `Xray-core` for the Xray backend; +* `hysteria` for Hysteria 1; +* `hysteria2` for Hysteria 2; +* `tun2socks` for application-managed TUN mode; +* the remaining cross-platform and platform-specific Python dependencies. + +There are no core-related optional extras and no separate core-installation step. The native binding wheels contain the +corresponding Go core and C++ Python extension. + +Furious does not pin a specific PySide6 release. pip selects a PySide6 version compatible with the chosen Python and +platform. This replaces the historical fixed “PySide6 6.1.0 minimum” guidance. + +## Compatibility + +Furious currently declares Python 3.8 or newer. The complete dependency set provides binary wheels for regular, +GIL-enabled CPython 3.8 through 3.14 on the combinations below: + +| Platform | Architectures | CPython | +|----------|---------------|---------| +| Windows 10 or later | x86-64 | 3.8-3.14 | +| Windows 10 or later | ARM64 | 3.11-3.14 | +| Linux (glibc/manylinux) | x86-64 | 3.8-3.14 | +| Linux (glibc/manylinux) | ARM64 | 3.10-3.14 | +| macOS 12 or later | Intel | 3.8-3.14 | +| macOS 12 or later | Apple Silicon | 3.10-3.14 | + +> [!TIP] +> CPython 3.10 or newer receives the current PySide6 and supporting-dependency releases. On Python 3.8 or 3.9, pip +> resolves the newest older releases that still support that interpreter. + +Important limits: + +* PyPy and other Python implementations are not supported by the native binding/PySide6 wheel set. +* Free-threaded CPython is not a supported Furious installation even though some individual core bindings publish + free-threaded wheels; PySide6 does not currently publish matching free-threaded wheels. +* The native bindings do not publish 32-bit wheels. +* Linux wheels target glibc-based manylinux systems, not musl-based distributions such as Alpine Linux. +* The special Windows 7-compatible PySide6 and Python builds used by Furious binary releases are not installed from + PyPI. Use a Windows 7 artifact from [GitHub Releases](https://github.com/LorenEteval/Furious/releases) instead. + +## If No Compatible Wheel Is Available + +When pip finds a matching wheel, installation is a direct download and no compiler is involved. If it prints messages +such as `Building wheel for Xray-core`, `hysteria`, `hysteria2`, or `tun2socks`, then no compatible binary wheel was +selected and pip is attempting the exceptional source-build path. + +You can require wheels and fail immediately instead of compiling: + +```bash +python -m pip install --only-binary=:all: Furious-GUI +``` + +First upgrade pip and confirm that the Python implementation, version, operating system, architecture, and Linux libc +match the compatibility section. Choosing a supported CPython build is usually simpler than compiling the bindings. + +### Building Native Bindings From Source + +Source builds are intended for unsupported environments and binding development. All four bindings use a native Go +archive plus a C++/pybind11 extension, but their Go requirements differ: + +| Binding | Current source-build requirements | +|---------|-----------------------------------| +| `Xray-core` | Go 1.26 or newer; CMake 3.15+; C/C++ compiler | +| `hysteria` | Go 1.20 or newer; CMake 3.15+; C/C++ compiler | +| `hysteria2` | Go 1.25.1 or newer; CMake 3.15+; C/C++ compiler | +| `tun2socks` | Go 1.26.3 or newer; CMake 3.15+; C/C++ compiler | + +pip's isolated build environment installs the declared Python build tools—CMake, pybind11, setuptools, and wheel—when +compatible distributions are available. Go and a native compiler must be installed separately and available in +`PATH`. + +Use GCC or Clang on Linux and Apple Clang on macOS. The binding projects use MinGW-w64 on Windows x86-64 and LLVM-MinGW +on Windows ARM64; MSVC and Cygwin are not their supported build paths. If Go module downloads are blocked on your +network, configure `GOPROXY` before starting the source build. + +See the binding repositories for current build details: + +* [Xray-core-python](https://github.com/LorenEteval/Xray-core-python) +* [hysteria-python](https://github.com/LorenEteval/hysteria-python) +* [hysteria2-python](https://github.com/LorenEteval/hysteria2-python) +* [tun2socks-python](https://github.com/LorenEteval/tun2socks-python) + +## Troubleshooting + +### pip cannot find a compatible distribution + +Check the interpreter and architecture: + +```bash +python -c "import platform, sys; print(sys.version); print(platform.machine()); print(platform.python_implementation())" +``` + +Then upgrade pip and retry. If the environment is outside the compatibility table, use a supported CPython build or a +prebuilt application from [GitHub Releases](https://github.com/LorenEteval/Furious/releases). + +### pip unexpectedly starts compiling + +Cancel the installation, upgrade pip, and retry with `--only-binary=:all:`. A source build is not required on a +supported wheel combination. + +### `Furious` is not found + +Make sure the virtual environment is active and verify the installation: + +```bash +python -m pip show Furious-GUI +python -m Furious +``` + +If `python -m Furious` works, the environment's scripts directory is not active or is missing from `PATH`.