codeflash/docs/getting-started/java-installation.mdx

---
title: "Java Installation"
description: "Install and configure Codeflash for your Java project"
icon: "java"
sidebarTitle: "Java Setup"
keywords:
  [
    "installation",
    "java",
    "maven",
    "gradle",
    "junit",
    "junit5",
    "tracing",
  ]
---

Codeflash supports optimizing Java projects using Maven or Gradle build systems. It works in two main ways:
1. Codeflash can optimize new java code written in a Pull Request through Github Actions.
2. Codeflash can optimize real workloads end to end. It uses a two-stage tracing approach to capture method arguments and profiling data from running Java program, then optimizes the hottest functions with that data.

### Prerequisites

Before installing Codeflash, ensure you have:

1. **Java 11 or above** installed
2. **Maven or Gradle** as your build tool
3. **A Java project** with source code under a standard directory layout

Good to have (optional):

1. **Unit tests** (JUnit 5 or JUnit 4) — Codeflash uses them alongside traced replay tests to verify correctness

<Steps>
<Step title="Install Codeflash CLI">

Codeflash uses Python to run its CLI. You can use uv as a package manager and installer for Python programs.
To install uv, run the following or [see these instructions](https://docs.astral.sh/uv/getting-started/installation/)

  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
Then install Codeflash as a uv tool.

```bash
uv tool install codeflash
```

</Step>
<Step title="Authenticate with Codeflash">

Codeflash uses cloud-hosted AI models. You need to authenticate before running any commands.

**Option A: Browser login (recommended)**

```bash
codeflash auth login
```

This opens your browser to sign in with your GitHub account. Your API key is saved automatically to your shell profile.

If you're on a remote server without a browser, a URL will be displayed that you can open on any device.

**Option B: API key**

1. Visit the [Codeflash Web App](https://app.codeflash.ai/) and sign up with your GitHub account (free tier available)
2. Navigate to the [API Key](https://app.codeflash.ai/app/apikeys) page to generate your key
3. Set it as an environment variable:

```bash
export CODEFLASH_API_KEY="your-api-key-here"
```

Add this to your shell profile (`~/.bashrc`, `~/.zshrc`) so it persists across sessions.

<Info>
If you skip this step, `codeflash init` will prompt you to authenticate interactively.
</Info>

</Step>
<Step title="Initialize your project (recommended)">

Navigate to your Java project root (where `pom.xml` or `build.gradle` is) and run:

```bash
codeflash init
```

The init command will:
1. **Auto-detect your project** — find your build tool, source root (e.g., `src/main/java`), test root (e.g., `src/test/java`), and test framework
2. **Confirm settings** — show the detected values and ask if you want to change anything
3. **Configure formatter** — let you set up a code formatter (e.g., Spotless, google-java-format)
4. **Install GitHub App** — offer to set up the [Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target) for automatic PR creation (see next step)
5. **Install GitHub Actions** — offer to add a CI workflow for automated optimization on PRs

Only non-default settings are written to your `pom.xml` properties (Maven) or `gradle.properties` (Gradle). For standard layouts, no config changes are needed.

<Info>
**Can I skip init?** Yes. For standard Maven/Gradle projects, Codeflash auto-detects your project structure from `pom.xml` or `build.gradle` at runtime. If you're already authenticated and your project uses a standard layout (`src/main/java`, `src/test/java`), you can skip straight to optimizing.

Init is recommended because it also sets up the GitHub App and Actions workflow, and lets you override paths for non-standard project layouts (e.g., multi-module projects where source is under `client/src/`).
</Info>

</Step>
<Step title="Install the Codeflash GitHub App (recommended)">

To have Codeflash create pull requests with optimizations automatically, install the GitHub App:

[Install Codeflash GitHub App](https://github.com/apps/codeflash-ai/installations/select_target)

Select the repositories you want Codeflash to optimize. This allows the codeflash-ai bot to open PRs with optimization suggestions in your repository.

<Info>
If you prefer to try Codeflash locally first, you can skip this step and use the `--no-pr` flag to apply optimizations directly to your local files (see next step).
</Info>

</Step>
<Step title="Run your first optimization">

Optimize a specific function:

```bash
codeflash --file src/main/java/com/example/Utils.java --function myMethod
```

If you installed the GitHub App, Codeflash will create a pull request with the optimization. If you haven't installed the app yet, or prefer to review changes locally first, add `--no-pr`:

```bash
codeflash --file src/main/java/com/example/Utils.java --function myMethod --no-pr
```

Or optimize all functions in your project:

```bash
codeflash --all
```

Codeflash will:
1. Discover optimizable functions in your source code
2. Generate tests and optimization candidates using AI
3. Verify correctness by running tests (JUnit 5, JUnit 4, or TestNG)
4. Benchmark performance improvements
5. Create a pull request with the optimization (or apply locally with `--no-pr`)

For advanced workflow tracing (profiling a running Java program), see [Trace & Optimize](/optimizing-with-codeflash/trace-and-optimize).

</Step>
</Steps>

## Supported build tools

| Build Tool | Detection | Test Execution |
|-----------|-----------|---------------|
| **Maven** | `pom.xml` | Maven Surefire plugin |
| **Gradle** | `build.gradle` / `build.gradle.kts` | Gradle test task |

## Supported test frameworks

| Framework | Support Level |
|-----------|-------------|
| **JUnit 5** | Full support (default) |
| **JUnit 4** | Full support |
| **TestNG** | Basic support |