Model or dataset
zhaoweih/Shadowsocks-Tutorial avatar
zhaoweih/Shadowsocks-Tutorial

Inside Shadowsocks-Tutorial: a Debian 12 walkthrough that ends with the firewall switched off

Easy-to-follow tutorials for beginners on using Shadowsocks to bypass internet restrictions.

2,699 stars521 forksShellLicense varies

At a glance

What is it?
This beginner guide provisions a Vultr or DigitalOcean server and installs shadowsocks-libev with a shell script fetched from GitHub at install time. The steps are concrete and dated, and three of them tell you more about the tutorial's own weak points than about Shadowsocks.
Who is it for?
Treat this repository as a provisioning checklist for a fresh Debian 12 host rather than as an explanation of Shadowsocks: every value it uses is spelled out, and none of the protocol reasoning is. Follow it literally and the part most likely to break is the Python 2 dependency that Debian 11 and Ubuntu 20.04 removed, which the script now works around, so a cached copy of the script is older than the fix.
Can I use it commercially?
Not without permission. GitHub finds no licence file in the repository, and without a licence all rights are reserved by default: you may read the code but not reuse it. Check the README, or ask the authors, before using it.
Is it still maintained?
Yes. The repository last received commits 33 days ago.
What is it written in?
Mainly Shell, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • zhaoweih/Shadowsocks-Tutorial2,699 ★ · +38
Star history
Repository2026-09-142026-11-15
zhaoweih/Shadowsocks-Tutorial2.7k2.7k

38 Stars in the last 62 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

The installer is fetched from the repository's own main branch with certificate checking off

The whole server side setup is three lines, and the tutorial is not the script itself, it points at the script:

bash
wget --no-check-certificate -O shadowsocks-all.sh https://raw.githubusercontent.com/zhaoweih/Shadowsocks-Tutorial/main/sh/shadowsocks-all.sh
chmod +x shadowsocks-all.sh
./shadowsocks-all.sh 2>&1 | tee shadowsocks-all.log

The top level tree has a sh/ directory, which is where that file lives in the project, so the guide is installing its own current content rather than a pinned release. --no-check-certificate turns off TLS verification for the download, which is the price of fetching raw content from a branch name. Piping through tee keeps the interactive menu output in shadowsocks-all.log, which is the only record of what the script chose if something goes wrong later. The document also expects you to right click to paste in Xshell and then press Enter, because the script output scrolls for a while before the first question.

The upstream installer is declared frozen while the tutorial keeps collecting patches

The script is not the author's work. The document credits @teddysun for the one click installer, links the original blog post at teddysun.com/486.html, and adds a parenthetical saying that since that author stepped back the command still works but the version is no longer updated. A second credit goes to @peinuanqin-nus for a repair to the script, referenced through issue 72 in this repository's issue tracker. The closing section points at another of the same author's posts for BBR congestion control and prints a root run line that fetches bbr.sh from github.com/teddysun/across/raw/master, makes it executable and runs it, after which the script asks for a reboot and expects the letter y. There are no GitHub releases on the project at all, and the last push to main is 2026-09-04, so the only thing that changes between two readers is whatever main happens to hold.

Failed to install python is a Debian 11 package removal, not a mistake in your setup

The most useful entry in the Q&A is the third one, marked solved, carrying the literal error `[Error] Failed to install python`. The cause given is that the install script's dependency list names the Python 2 packages python, python-dev and python-setuptools, and those packages were removed from Debian 11 and Ubuntu 20.04 onwards, so apt cannot find them and aborts. The text is explicit that this happens even when you pick the libev build, which is the build the walkthrough tells you to choose. The fix lives in the script rather than in the tutorial: it now checks whether Python 2 is present and falls back to the python3 package names if not, and readers holding an older copy are told to download the script again. The failure is tracked in issue #27. Since the walkthrough tells you to deploy Debian 12 x64, the documented target system is newer than the package names the script originally used.

The last installation step switches the host firewall off

The document closes its installation phase by pasting this into the server session:

bash
sudo ufw disable

The same command returns in the Q&A under the symptom of a server that pings but will not accept a connection, which is attributed to Vultr turning a firewall on by default, and the text says to confirm the result with `ufw status`, where a reading of inactive means it is off. A neighbouring note says `systemctl status firewalld` applies only to CentOS style systems, and the sentence about what happens on Debian and Ubuntu stops after half a line. Earlier in the walkthrough the same pattern appears for a blocked address: a single request timeout is described as packet loss and is acceptable, repeated timeouts mean deleting the server and deploying another one, and a server that pings but that Xshell cannot reach is diagnosed as a blocked port, with the advice to change region or provider.

Hourly billing, a referral query string and a default backup toggle

The VPS step is written as a cost argument as much as a technical one. Vultr and DigitalOcean are described as servers you can deploy and destroy at will, billed hourly, at 5 dollars a month or roughly 0.007 dollars an hour, with the note that deleting an address that turns out to be blocked costs about 0.1 dollars. The registration step carries a Vultr address with ref=7370522 in the query string, so the author earns a referral credit from the signups the guide produces. The payment detail is specific: the minimum top up is 5 dollars by paypal with a domestic card, or 10 dollars through Alipay. The cheapest 2.5 dollar plan is described as usually sold out, automatic backup is on by default and costs 1 dollar a month so the document tells you to uncheck it, Frankfurt in Germany is recommended because Japanese servers were abused and many addresses were blocked, and startup takes 1 to 3 minutes until the status line shows Running in green.

An iOS install needs an App Store account registered from the region you want

The client section covers Windows, Mac, Android, Linux and iOS, and the iOS part is where the guide stops being a technical document. It states that apps supporting Shadowsocks were pulled from the Chinese App Store, so the reader has to register an account outside that region and switch to it, and it suggests buying a foreign App Store account on Taobao for anyone who does not want the registration effort. Apple's current payment policy is described as the real obstacle: at the payment step the None option is unavailable unless the local IP matches the region, so registering a UK account needs a UK IP, which means a working proxy is required before you have one. The client it suggests is Potatso Lite, with a note that any other Shadowsocks capable app will do, and download links are given for shadowsocks-windows, shadowsocks-android, ShadowsocksX-NG and a shadowsocks-qt5 installation wiki page.

PAC mode splits traffic using the gfwlist definitions

Once the four server values are typed into the client, the walkthrough insists on PAC mode instead of global mode and explains the difference in one line each: PAC sends domestic sites out through the domestic address and blocked sites through the server, while global sends everything through the server. The PAC definitions are said to be kept in the gfwlist project, and readers are asked to open issues for sites that PAC cannot reach. The example values used from end to end are a password of abc123456, port 12853 out of the range 1 to 65535, the libev server build chosen by typing 4, xchacha20-ietf-poly1305 chosen by typing 13, and simply-obfs left at its default with a bare Enter. Two further documents in the tree extend the same setup, one on kcptun for speed and one on pointing git clone at the proxy.

The Q&A is emailed failure reports, and two of the four fixes live in other articles

The Q&A section says it collects questions sent by email, and the first entry is a server without wget at all, reported on Linode in Singapore running CentOS 7, where the resolution is a link to a third party article about installing wget rather than a command in this document. The second entry is Google Scholar returning a message about a computer or network sending automated queries, and the explanation offered is that Google detects many VPS addresses as proxies, so the advice is to change servers, or to use a Google Scholar mirror if none is available. The last two entries are the firewall case and the Python case described earlier. The service control commands at the end cover four builds, with start, stop, restart and status under /etc/init.d for shadowsocks-libev, shadowsocks-python, shadowsocks-r and shadowsocks-go, and removal is `./shadowsocks-all.sh uninstall` followed by picking the matching build from the prompt.

Editorial conclusion

Treat this repository as a provisioning checklist for a fresh Debian 12 host rather than as an explanation of Shadowsocks: every value it uses is spelled out, and none of the protocol reasoning is. Follow it literally and the part most likely to break is the Python 2 dependency that Debian 11 and Ubuntu 20.04 removed, which the script now works around, so a cached copy of the script is older than the fix. Check three things before you script any of it: whether the machine you are on still has a package manager that can fetch the script over wget, what your firewall state is before and after the ufw step, and whether the license terms you need are written down anywhere, because no license file appears in the repository.

Frequently asked questions

Can Shadowsocks be detected?

The repository does not discuss detection at all. What it documents is buying a VPS on Vultr or DigitalOcean, deploying Debian 12 x64, and installing shadowsocks-libev through a fetched shell script, so any answer about protocol behaviour has to come from somewhere else.

Does Shadowsocks hide my IP address?

Not answered here either. The closest fact the document gives is its description of PAC mode, where blocked sites go out through the server while domestic sites keep the domestic address, with the PAC definitions taken from the gfwlist project.

Which Shadowsocks build does this tutorial install?

The libev server build, chosen by typing 4 at the menu, followed by a password, a port between 1 and 65535, and xchacha20-ietf-poly1305 chosen by typing 13, with simply-obfs left at its default. The command reference at the end also lists python, r and go builds under /etc/init.d.

Why does the Shadowsocks install fail with Failed to install python?

The script's dependency list names the Python 2 packages python, python-dev and python-setuptools, which were removed from Debian 11 and Ubuntu 20.04 onwards, so apt aborts even when you pick the libev build. The script now falls back to python3 packages, so a cached copy has to be downloaded again; the fix is tracked in issue #27.

How do I uninstall after following the Shadowsocks tutorial?

Run `./shadowsocks-all.sh uninstall` on the server and pick the build you installed when the prompt asks. The document also tells you to check `ufw status` for an inactive reading after `sudo ufw disable`, and it does not describe putting the firewall back.

Official sources

  1. Issues
  2. Project website
  3. README
  4. zhaoweih/Shadowsocks-Tutorial on GitHub
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/zhaoweih-shadowsocks-tutorial.svg)](https://hysenlabs.com/projects/zhaoweih-shadowsocks-tutorial)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/zhaoweih-shadowsocks-tutorial.svg)](https://hysenlabs.com/projects/zhaoweih-shadowsocks-tutorial)

Was this useful?