Install Langfuse on Your Local Device

How I spin up Langfuse locally with Docker, seed a project, and hook it to a Python app—plus troubleshooting notes.
November 4, 2025

Why I run Langfuse locally

Langfuse helps me see prompt + completion tokens, latency, and traces for LLM calls. The hosted version is great, but for experiments I prefer local:

  • No data leaves my machine
  • I can pin versions and test breaking changes safely
  • Faster iterations because logs and DB are local

Homepage: langfuse.com

Prereqs

  • Docker + Docker Compose
  • Git
  • ~2 GB free RAM for the Postgres + app containers

Step-by-step: bring up Langfuse

  1. Clone the repo
git clone https://github.com/langfuse/langfuse.git
cd langfuse
  1. Set env vars (example .env)
POSTGRES_PASSWORD=langfuse
LANGFUSE_INIT_USER_EMAIL=me@example.com
LANGFUSE_INIT_USER_PASSWORD=changeme

Use throwaway values locally; swap to strong secrets in real deployments.

  1. Start it
docker compose up

First run pulls images. You’ll get Postgres + Langfuse Web.

  1. Open the UI
    Visit http://localhost:3000, log in with the creds above, create a Project, and note the Public Key / Secret Key / Base URL.

接入 Python 代码（示例）

Install the SDK:

pip install langfuse

Add a .env (or export env vars):

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_BASE_URL=http://localhost:3000

Example call:

from langfuse.openai import openai

completion = openai.ChatCompletion.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hi"}],
)
print(completion.choices[0].message["content"])

You should now see traces, tokens, and latency in the Langfuse UI.

Day-to-day notes

  • Data lives in local Postgres. docker compose down -v wipes volumes—use carefully.
  • Port clashes: Langfuse defaults to 3000, Postgres to 5432; change the mappings if needed.
  • Pin versions: note the commit/tag in your .env so SDK bumps don’t get ahead of the DB schema.

Quick fixes

  • “address already in use”: free up 3000/5432 or change the compose ports.
  • Can’t log in/create project: confirm .env is loaded (docker compose config to inspect).
  • SDK 401: re-copy the keys and make sure LANGFUSE_BASE_URL points to localhost.

Once it’s stable locally, add persistent volumes, backups, or wire it to your remote models—privacy intact, faster prompt experiments.