This page covers everything you need to get alterself installed and properly configured before you write your first line of bot code. You will install the library, learn how to pass your token securely through environment variables, tune logging to match your workflow, and optionally route traffic through a proxy. If you just want to get something running as fast as possible, see the Quick Start guide instead.
Requirements
alterself requires Python 3.10 or newer. The library relies on structural pattern matching, ParamSpec, and other language features introduced in 3.10 that cannot be polyfilled on older interpreters. You can check your current version with:
No other system-level dependencies are required. All Python dependencies are declared in pyproject.toml and installed automatically by pip.
Installation
Choose the installation method that fits your workflow.
Installing from source with -e (editable mode) links the package directly to the cloned directory. Any changes you make to the source are immediately reflected without reinstalling, which is useful if you want to contribute to alterself or pin to an unreleased commit.
Use a virtual environment to keep your alterself installation isolated from other projects. Run python -m venv .venv && source .venv/bin/activate (or .venv\Scripts\activate on Windows) before installing.
Token Setup
Your Discord user token is a secret credential with full access to your account. You should never hardcode it in a source file. The recommended pattern is to read it from an environment variable at startup:
os.environ["DISCORD_TOKEN"] raises a KeyError immediately if the variable is not set, which prevents your selfbot from starting with an empty token and producing confusing errors later. os.environ.get("PREFIX", "!") falls back to ! if you have not set a custom prefix, making the prefix optional to configure.
Set the environment variable in your shell before running the bot:
For longer-running deployments, consider storing secrets in a .env file (excluded from version control via .gitignore) and loading it with a library such as python-dotenv, or use your platform’s native secrets manager.
Never commit your token to a Git repository, paste it in a chat, or include it in any file that leaves your machine. If you accidentally expose your token, change your Discord account password immediately. This invalidates all existing tokens.
Logging
alterself uses Python’s standard logging module. You can control verbosity by passing log_level to bot.run():
logging.INFO is a good default for most use cases. Switch to logging.DEBUG when you are diagnosing unexpected behaviour. It will show you every gateway opcode and outbound HTTP call. Use logging.WARNING in production if you want a clean terminal.
You can configure the log format and handlers yourself before calling bot.run() by calling logging.basicConfig() with your preferred settings. alterself will respect any handler configuration you have already established.
Proxy
If you need to route your selfbot’s traffic through an HTTP or SOCKS proxy, for example to assign a consistent IP address or to work around network restrictions, pass the proxy parameter to the Client constructor:
Both the gateway WebSocket connection and all HTTP API calls will be routed through the specified proxy. SOCKS5 proxies are supported using the socks5:// scheme. Leave the parameter unset to connect directly.
Async Entry Point
bot.run() creates and manages its own asyncio event loop, which makes it convenient as a top-level entry point. If you are integrating alterself into a larger async application that already has a running event loop, for example alongside a web server or another async library, use await bot.start() instead:
bot.start() is a coroutine that connects to the gateway and returns only when the connection is closed. If you want to run the selfbot alongside other long-lived coroutines, schedule them with asyncio.gather() or asyncio.create_task() before awaiting bot.start().