Where Are Nitter Sessions Stored? File Paths and Configuration Guide

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:

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:

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

Setting within Nim code before initialization:

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:

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:

{"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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}