torsocks: Route App Traffic Through Tor

torsocks: Route traffic through Tor

A pragmatic intro to using torsocks to redirect an application’s network traffic via the Tor network. By default, torsocks talks to the Tor SOCKS proxy at 127.0.0.1:9050, so make sure Tor is running locally before you start.

Quick start examples

  • Run a command through Tor
torsocks curl https://check.torproject.org/api/ip
  • Check if the current shell is Tor-enabled
torsocks show
  • Spawn a new Tor-enabled shell
torsocks --shell
  • Isolate traffic through a separate Tor circuit
torsocks -i curl https://check.torproject.org/api/ip
  • Use a custom Tor proxy address/port
torsocks -a 127.0.0.1 -P 9150 curl https://check.torproject.org/api/ip

When to use torsocks

  • You want a quick way to route a single application through Tor without configuring the app itself.
  • You’re testing how a program behaves behind a Tor circuit.
  • You’re scripting tasks that should avoid leaking your IP address.

Common pitfalls

  • Tor must be running locally. If Tor isn’t active, torsocks will fail to connect to 127.0.0.1:9050 by default.
  • DNS leaks: Tor only routes your traffic through the SOCKS proxy. If an application performs DNS resolution outside Tor, leaks may occur. Prefer using URL access that won’t leak DNS, or disable direct DNS lookups in the app if possible.
  • IPv6: Tor’s SOCKS proxy typically handles IPv4. If your application prefers IPv6, ensure Tor is configured to handle it or force IPv4 when using torsocks.
  • Not all programs cooperate with torsocks. Some apps bypass environment wrappers or spawn child processes that don’t inherit the LD_PRELOAD wrapper used by torsocks.

How torsocks works (short)

  • torsocks uses LD_PRELOAD to wrap network calls and redirect them through the Tor SOCKS proxy by default.
  • It assumes Tor’s SOCKS proxy is at 127.0.0.1:9050 unless you override with -a/—address and -P/—port.

Tips and best practices

  • Verify your IP behind Tor once in a while:
curl -sS https://check.torproject.org/api/ip
  • If you need to force a specific Tor circuit, use the -i/—isolate option to ensure separate streams don’t share a circuit with other traffic.
  • For long-running sessions, consider a dedicated Tor-enabled shell with torsocks —shell to avoid repeated LD_PRELOAD toggling.

Troubleshooting

  • If torsocks show returns but your traffic doesn’t appear to be Torged, check:
    • Is Tor running? (systemctl status tor or torctl)
    • Is the SOCKS port correct? 127.0.0.1:9050 by default.
    • Does the application perform DNS lookups outside of the wrapper?

Quick reference

  • Run a command through Tor:
torsocks {{command}}
  • Enable or disable Tor in this shell:
. torsocks {{on|off}}
  • Spawn a new Tor-enabled shell:
torsocks --shell
  • Check if current shell is Tor enabled:
torsocks show
  • Isolate traffic through a different Tor circuit:
torsocks {{[-i|--isolate]}} {{command}}
  • Connect to a Tor proxy on a specific address/port:
torsocks {{[-a|--address]}} {{ip}} {{[-P|--port]}} {{port}} {{command}}

Bottom line

torsocks is a pragmatic tool to quickly sandbox a process’s network traffic inside the Tor network. Use it for testing, privacy-focused commands, or when you need to avoid IP leakage for a single task. Always validate that your traffic is indeed exiting via Tor if that is a requirement.

See Also