# Where Are Nitter Sessions Stored? File Paths and Configuration Guide

> Discover where Nitter sessions are stored. Learn about the sessions file path and configuration using the NITTER_SESSIONS_FILE variable for secure authentication management.

- Repository: [Zed/nitter](https://github.com/zedeus/nitter)
- Tags: how-to-guide
- Published: 2026-09-04

---

**Nitter stores authentication sessions in a JSON-Lines file controlled by the `NITTER_SESSIONS_FILE` environment variable, defaulting to `./sessions.jsonl` in the server's working directory.**

The open-source Twitter front-end **Nitter** (zedeus/nitter) relies on authenticated sessions to access Twitter's API and circumvent rate limits. Understanding where Nitter sessions are stored is critical for secure deployment, backup strategies, and troubleshooting authentication issues in self-hosted instances.

## Default Session Storage Location

According to the zedeus/nitter source code, the session file path is defined in `src/nitter.nim` at line 22 using the `getEnv` procedure with a hardcoded default:

```nim
sessionsPath = getEnv("NITTER_SESSIONS_FILE", "./sessions.jsonl")

```

If the `NITTER_SESSIONS_FILE` environment variable is not set, Nitter looks for a file named `sessions.jsonl` in the directory where the server process is started. This path is relative to the current working directory at runtime, not the installation directory.

## Customizing the Session File Path

To override the default location, set the `NITTER_SESSIONS_FILE` environment variable before starting the server. This is essential for containerized deployments or when following Linux filesystem hierarchy standards.

**Setting the environment variable in Bash:**

```bash
export NITTER_SESSIONS_FILE="/var/lib/nitter/sessions.jsonl"
nimble run

```

**Setting within Nim code before initialization:**

```nim
import os
putEnv("NITTER_SESSIONS_FILE", "/var/lib/nitter/sessions.jsonl")

```

## Session File Format and Initialization

The sessions file uses **JSON-Lines format** (one JSON object per line). During startup, the `initSessionPool` procedure called at line 24 of `src/nitter.nim` loads and validates this file:

```nim
initSessionPool(cfg, sessionsPath)

```

The parsing logic resides in `src/experimental/parser/session.nim`, which converts each JSON object into an internal `Session` record containing either OAuth tokens or cookie credentials.

**Example JSON-Lines content:**

```json
{"kind":"oauth","username":"myuser","oauthToken":"12345-abcdef","oauthTokenSecret":"secret"}
{"kind":"cookie","username":"another","ct0":"abc123","authToken":"def456"}

```

## Session Pool Management

Once loaded, sessions are managed by the authentication module in `src/auth.nim`, which handles request routing and rate limit distribution across the pool. For testing session validity without running the full server, use the utility script `tools/test_sessions.nim` to verify your `.jsonl` file format and credentials.

## Summary

- Nitter sessions are stored in a JSON-Lines file defaulting to `./sessions.jsonl` in the working directory
- The storage location is controlled by the `NITTER_SESSIONS_FILE` environment variable as implemented in `src/nitter.nim`
- Sessions are parsed at startup by `initSessionPool` using the parser defined in `src/experimental/parser/session.nim`
- Each line in the file represents a distinct authentication session (OAuth or cookie-based) used for API requests

## Frequently Asked Questions

### How do I change where Nitter stores its sessions?

Set the `NITTER_SESSIONS_FILE` environment variable to an absolute path before starting the server. This overrides the default `./sessions.jsonl` fallback defined in the source code at `src/nitter.nim:22`.

### What format does the Nitter sessions file use?

The file uses JSON-Lines format (**.jsonl**), where each line is a separate JSON object representing one session. Valid session types include OAuth credentials (`oauthToken`, `oauthTokenSecret`) or browser cookies (`ct0`, `authToken`).

### Can I store multiple sessions in one file?

Yes. The JSON-Lines format supports multiple session objects on separate lines. Nitter loads all valid sessions into the session pool to rotate requests and distribute Twitter rate limits across multiple accounts.

### Why is my sessions file not being detected?

Ensure the file exists at the path specified by `NITTER_SESSIONS_FILE` (or `./sessions.jsonl` by default) and that the server process has read permissions. Remember that the default path is relative to the working directory where you start Nitter, not the location of the binary itself.