Skip to main content
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
Install Phoenix using 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

# 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

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

​
TypeScript/JavaScript Packages

For Node.js applications: 
npm install @arizeai/phoenix-otel
See the TypeScript documentation for more details.

​
Environment Variables

Phoenix can be configured using environment variables:
VariableDescriptionDefault
PHOENIX_PORTPort for the web server6006
PHOENIX_HOSTHost to bind to0.0.0.0
PHOENIX_SQL_DATABASE_URLDatabase URL (supports SQLite and PostgreSQL)SQLite in working directory
PHOENIX_WORKING_DIRDirectory for storing dataCurrent directory
PHOENIX_TELEMETRY_ENABLEDEnable/disable usage telemetrytrue
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 install --upgrade arize-phoenix

​
Troubleshooting

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.
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
Check the container logs:
docker logs phoenix
Common issues include port conflicts (something else using port 6006) or database connection problems.
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.

Build docs developers (and LLMs) love

Get started for freeTalk to us