mirror of
https://github.com/LorenEteval/Furious.git
synced 2026-10-10 00:08:11 +03:00
Rewrite PyPI installation guide
Signed-off-by: Loren Eteval <loren.eteval@proton.me>
Loren Eteval
+151
-52
@@ -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
|
||||
```
|
||||
```
|
||||
|
||||
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`.
|
||||
|
||||
Reference in New Issue
Block a user