> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guilt.icu/llms.txt
> Use this file to discover all available pages before exploring further.
# Installing alterself and Setting Up Your Environment
> Install alterself via pip or from source, configure your Discord token securely, and set up logging for development and production.
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](/quickstart) 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:
```bash theme={null}
python --version
```
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.
```bash pip (recommended) theme={null}
pip install alterself
```
```bash From source theme={null}
git clone https://github.com/alterself/alterself.git
cd alterself
pip install -e .
```
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:
```python theme={null}
import os, alterself
bot = alterself.Client(
token = os.environ["DISCORD_TOKEN"],
prefix = os.environ.get("PREFIX", "!"),
)
```
`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:
```bash theme={null}
export DISCORD_TOKEN="your_token_here" # macOS / Linux
set DISCORD_TOKEN=your_token_here # Windows Command Prompt
$env:DISCORD_TOKEN="your_token_here" # Windows PowerShell
```
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()`:
```python theme={null}
import logging, os, alterself
bot = alterself.Client(
token = os.environ["DISCORD_TOKEN"],
prefix = ".",
)
# Choose one level depending on your needs:
# Development: prints gateway frames, HTTP requests, and event dispatch details.
bot.run(log_level=logging.DEBUG)
# Normal operation: prints connection events, reconnects, and handled errors.
bot.run(log_level=logging.INFO)
# Quiet mode: only prints warnings and fatal errors.
bot.run(log_level=logging.WARNING)
```
`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:
```python theme={null}
import os, alterself
bot = alterself.Client(
token = os.environ["DISCORD_TOKEN"],
prefix = ".",
proxy = "http://user:password@proxy.example.com:8080",
)
```
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:
```python theme={null}
import asyncio, os, alterself
bot = alterself.Client(
token = os.environ["DISCORD_TOKEN"],
prefix = ".",
)
async def main():
# Other async setup can go here.
await bot.start()
asyncio.run(main())
```
`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()`.