Installation

Install Phoenix using pip, conda, Docker, or from source

Phoenix can be installed in multiple ways depending on your environment and preferences.

Python Package

Requirements

Phoenix requires:

• Python: 3.10, 3.11, 3.12, or 3.13
• Operating System: Linux, macOS, or Windows

pip (Recommended)

Install Phoenix using pip:

pip

pip install arize-phoenix

The arize-phoenix package includes:

• Phoenix server
• Tracing capabilities
• Evaluation tools
• Client libraries for interacting with Phoenix

The full arize-phoenix package is recommended for most users. If you only need specific functionality (like just the client), see the Lightweight Packages section below.

conda

Install Phoenix using conda:

conda install -c conda-forge arize-phoenix

uv

If you’re using uv for faster Python package management:

uv pip install arize-phoenix

Verify Installation

Verify that Phoenix is installed correctly:

python -c "import phoenix; print(phoenix.__version__)"

You can also check the installed version:

phoenix --version

Docker

Phoenix provides official Docker images hosted on Docker Hub.

Pull the Latest Image

docker pull arizephoenix/phoenix:latest

Run Phoenix in Docker

Basic

# Run in foreground
docker run -p 6006:6006 -p 4317:4317 arizephoenix/phoenix

# Run in background
docker run -d --name phoenix -p 6006:6006 -p 4317:4317 arizephoenix/phoenix

Exposed Ports:

• 6006: Phoenix web UI and HTTP API
• 4317: gRPC endpoint for OpenTelemetry traces
• 9090: Prometheus metrics (optional)

Docker Compose

For a complete setup with PostgreSQL, create a docker-compose.yml:

docker-compose.yml

services:
  phoenix:
    image: arizephoenix/phoenix:latest
    ports:
      - "6006:6006"
      - "4317:4317"
    environment:
      - PHOENIX_SQL_DATABASE_URL=postgresql://postgres:postgres@db:5432/postgres
    depends_on:
      - db
      
  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=postgres
      - POSTGRES_PASSWORD=postgres
      - POSTGRES_DB=postgres
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"

volumes:
  postgres_data:

Run with:

docker compose up -d

Access Phoenix at http://localhost:6006.

Building from Source (Docker)

To build the Docker image yourself:

git clone https://github.com/Arize-ai/phoenix.git
cd phoenix
docker build -t phoenix .

For ARM64 architectures (like Apple Silicon or Raspberry Pi), the Dockerfile automatically detects and uses the appropriate base image.

Installing from Source

For development or to get the latest unreleased features:

1. Clone the repository

   git clone https://github.com/Arize-ai/phoenix.git
   cd phoenix
   
2. Install uv (if not already installed)

   Phoenix uses uv for dependency management:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   
3. Install dependencies and build

   # Install in development mode
   uv sync --all-extras
   
   # Activate the virtual environment
   source .venv/bin/activate  # On Unix/macOS
   # or
   .venv\Scripts\activate  # On Windows
   
4. Run Phoenix

   python -m phoenix.server.main serve
   

Lightweight Packages

If you have a deployed Phoenix instance and only need specific functionality, you can install lightweight sub-packages:

Python Sub-packages

phoenix-otel

# Lightweight OpenTelemetry wrapper with Phoenix defaults
pip install arize-phoenix-otel

TypeScript/JavaScript Packages

For Node.js applications:

phoenix-otel

npm install @arizeai/phoenix-otel

See the TypeScript documentation for more details.

Environment Variables

Phoenix can be configured using environment variables:

Variable	Description	Default
PHOENIX_PORT	Port for the web server	6006
PHOENIX_HOST	Host to bind to	0.0.0.0
PHOENIX_SQL_DATABASE_URL	Database URL (supports SQLite and PostgreSQL)	SQLite in working directory
PHOENIX_WORKING_DIR	Directory for storing data	Current directory
PHOENIX_TELEMETRY_ENABLED	Enable/disable usage telemetry	true

Phoenix uses SQLite by default for simplicity. For production deployments, we recommend using PostgreSQL. See the Deployment guide for more information.

Upgrading Phoenix

To upgrade to the latest version:

pip

pip install --upgrade arize-phoenix

Troubleshooting

Import errors after installation

If you encounter import errors, ensure you’re using a compatible Python version:

python --version

Phoenix requires Python 3.10 or higher. If you’re using an older version, upgrade Python or create a new virtual environment with a compatible version.

Permission denied errors on Linux/macOS

If you get permission errors during installation, try using a virtual environment:

python -m venv phoenix-env
source phoenix-env/bin/activate
pip install arize-phoenix

Docker container exits immediately

Check the container logs:

docker logs phoenix

Common issues include port conflicts (something else using port 6006) or database connection problems.

SQLite database locked errors

This can happen if multiple Phoenix instances try to use the same SQLite database. Either:

• Use different working directories for each instance
• Switch to PostgreSQL for multi-instance deployments
• Ensure only one Phoenix instance is running at a time

Next Steps

Now that you have Phoenix installed:

Quickstart Guide

Get Phoenix running and trace your first application.

Deployment Guide

Learn how to deploy Phoenix for production use.