Skip to content

Installation

This guide uses uv, a fast Python package manager that handles Python installation automatically. If you prefer traditional tools, see the pip installation guide.

1. Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
Other installation methods
  • macOS with Homebrew: brew install uv
  • Windows with winget: winget install --id=astral-sh.uv -e

See the uv installation docs for more options.

After installation, you may need to restart your terminal or run source ~/.bashrc (Linux) / source ~/.zshrc (macOS) for the uv command to be available.

2. Create a project

Run the following command to create a new uproot project:

uv run --with uproot-science uproot setup my_project

This command:

  1. Downloads and installs the latest version of uproot
  2. Creates a new directory called my_project
  3. Generates starter files including a sample experiment

You should see output like this:

📂 A new project has been created in 'my_project'.
✅ 'main.py' and some other files have been written.
...

3. Run uproot

Navigate to your new project and run the command shown in the output above:

cd my_project
uv run uproot run

The first run will set up a virtual environment and install dependencies automatically. You'll see:

INFO:     Started server process [...]
INFO:     Waiting for application startup.
INFO:uproot:This is uproot 0.0.1 (https://uproot.science/)
INFO:uproot:Server is running at http://127.0.0.1:8000/

Tip

You can stop the server with Ctrl+C.

4. Access the admin interface

The server output includes an auto-login URL that looks like:

Auto login:
     http://127.0.0.1:8000/admin/login/#aBcDeFgHiJkL...

Click that URL or copy it to your browser to log in automatically. This auto-login feature only appears when using the default administrator with an empty password.

5. Try the sample experiment

Your new project includes a sample experiment: a two-player prisoner's dilemma.

Once logged in, you can start it from the admin interface.

Set up AI-assisted development

We recommend developing uproot experiments with an agentic coding tool such as Claude Code or Codex. These tools understand uproot's patterns and can build pages, write form logic, set up multiplayer interactions, and debug issues far faster than working from scratch.

If your coding agent supports skills (Claude Code, Codex, and others do), install the uproot skill to give it deep knowledge of uproot's API:

mrpg/uproot-skill

Follow the instructions in the repository to set it up. Once installed, the agent can work with uproot's page lifecycle, fields, SmoothOperators, data model, and multiplayer features out of the box.

Tip

Even without the skill, agentic coding tools work well if you clone the uproot-examples and uproot-docs repositories alongside your project — this gives the agent direct access to a lot of important information. Just tell your agent to "kindly inhale the examples and the docs."

What's next?

Now that uproot is running, you can:

Troubleshooting

uv command not found

If you get "command not found" after installing uv:

  1. Close and reopen your terminal
  2. Or run source ~/.bashrc (Linux) / source ~/.zshrc (macOS)
  3. Or add ~/.local/bin to your PATH manually

Permission errors on Linux

If you encounter permission errors, make sure you're not running as root. uv is designed to work in user space.

Port already in use

If port 8000 is already in use, you can specify a different port:

uv run uproot run --port 8001

Getting help

See here.