This page describes how to set up your workstation to check out source code, make simple changes in Android Studio, and upload commits to Gerrit for review.
This page does not cover best practices for the content of changes. Please see Life of a Jetpack Feature for details on creating and releasing a library or API Guidelines for best practices regarding library development.
This section will help you install the repo tool, which is used for Git branch and commit management. If you want to learn more about repo, see the Repo Command Reference.
NOTE The repo tool uses Git submodules under the hood, and it is possible to skip using the tool in favor of using submodules directly. If you prefer to use submodules, look for notes anywhere that repo is mentioned in this document. Submodule users can skip Workstation setup.
To ensure git can detect diffs and renames across significant changes (namely, the androidx.* package rename), we recommend that you set the following git config properties:
git config --global merge.renameLimit 999999 git config --global diff.renameLimit 999999
First, download repo using curl.
test -d ~/bin || mkdir ~/bin curl https://storage.googleapis.com/git-repo-downloads/repo \ > ~/bin/repo && chmod 700 ~/bin/repo
Then, modify ~/.zshrc (or ~/.bash_profile if using bash) to ensure you can find local binaries from the command line. We assume you're using zsh, but the following should work with bash as well.
export PATH=~/bin:$PATH
NOTE: When using quotes (
"~/bin"),~does not expand and the path is invalid. (Possiblybashonly?)
Next, if your machine has multiple versions of Python installed then you will need to add the following lines to ~/.zshrc (or ~/.bash_profile if using bash) to force the repo command to run with python3:
# Force repo to run with Python3 function repo() { command python3 ~/bin/repo $@ }
Finally, you will need to either start a new terminal session or run source ~/.zshrc (or source ~/.bash_profile if using bash) to enable the changes.
NOTE: If you encounter the following warning about Python 2 being no longer supported, you will need to install Python 3 from the official website.
repo: warning: Python 2 is no longer supported; Please upgrade to Python 3.6+.
NOTE: If you encounter an SSL
CERTIFICATE_VERIFY_FAILEDerror:Downloading Repo source from https://gerrit.googlesource.com/git-repo fatal: Cannot get https://gerrit.googlesource.com/git-repo/clone.bundle fatal: error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (\_ssl.c:997)Run the
Install Certificates.commandin the Python folder of Application (e.g./Applications/Python\ 3.11/Install\ Certificates.command). You may also need to installpipviapython3 -m ensurepipto run this command. For more information about SSL/TLS certificate validation, you can read the “Important Information” displayed during Python installation.
Sorry, Windows is not a supported platform for AndroidX development.
Before you can upload changes, you will need to associate your Google credentials with the AOSP Gerrit code review system by signing in to android-review.googlesource.com at least once using the account you will use to submit patches.
Next, you will need to set up authentication. This will give you a shell command to update your local Git cookies, which will allow you to upload changes.
Finally, you will need to accept the CLA for new contributors.
Like ChromeOS, Chromium, and the Android OS, we develop in the open as much as possible. All feature development occurs in the public androidx-main repo branch of the Android Open Source Project, with majority of the code in the frameworks/support git repository.
As of 2025-08-18, you will need about 60 GB for a clean checkout or 160 GB for a fully-built checkout with history.
Use the following commands to check out your branch.
All development should occur in this branch unless otherwise specified by the AndroidX Core team.
The following command will check out the public main development branch:
mkdir androidx-main && cd androidx-main repo init -u https://android.googlesource.com/platform/manifest \ -b androidx-main --partial-clone --clone-filter=blob:limit=10M repo sync -c -j32
NOTE On MacOS, if you receive an SSL error like SSL: CERTIFICATE_VERIFY_FAILED you may need to install Python3 and boot strap the SSL certificates in the included version of pip. You can execute Install Certificates.command under /Applications/Python 3.6/ to do so.
NOTE On MacOS, if you receive a Repo or GPG error like repo: error: "gpg" failed with exit status -6 with cause md_enable: algorithm 10 not available you may need to install a build of gpg that supports SHA512, such as the latest version available from Homebrew using brew install gpg.
The git superproject contains a history of the matching exact commits of each git repository over time, and it can be checked out directly via git
NOTE: If the repo manifest changes -- for example when we update the version of
platform-toolsby pointing it to a different git project -- you may see the following error duringrepo sync:error.GitError: Cannot fetch --force-sync not enabled; cannot overwrite a local work tree. ... error: Unable to fully sync the tree. error: Downloading network changes failed.This indicates that Studio or some other process has made changes in the git project that has been replaced or removed. You can force
repo syncto discard these changes and check out the correct git project by adding the--force-syncargument:repo sync -j32 --force-sync
androidx-main has a publicly-accessible code search that allows you to explore all of the source code in the repository. Links to this URL may be shared on the public issue tracked and other external sites.
androidx-mainWe recommend setting up a custom search engine in Chrome as a faster (and publicly-accessible) alternative to cs/.
chrome://settings/searchEnginesAdd buttonhttps://cs.android.com/search?q=%s&ss=androidx%2Fplatform%2Fframeworks%2FsupportAdd buttonNow you can select the Chrome omnibox, type in csa and press tab, then enter a query to search for, e.g. AppCompatButton file:appcompat, and press the Enter key to get to the search result page.
Library development uses a curated version of Android Studio to ensure compatibility between various components of the development workflow.
From the frameworks/support directory, you can use
PROJECT_PREFIX=:core:,:work: ./gradlew :studio
where PROJECT_PREFIX is comma separated list of project prefixes for projects you want to work on. This will automatically download and run the correct version of Studio to work on the selected libraries.
If you want to open all projects, you can run
./studiow all
Next, open the framework/support project root from your checkout. If Studio asks you which SDK you would like to use, select Use project SDK. Importing projects may take a while, but once that finishes you can use Studio as you normally would for application or library development -- right-click on a test or sample to run or debug it, search through classes, and so on.
NOTE: You should choose “Use project SDK” when prompted by Studio. If you picked “Android Studio SDK” by mistake, don't panic! You can fix this by opening
File > Project Structure > Platform Settings > SDKsand manually setting the Android SDK home path to<project-root>/prebuilts/fullsdk-<platform>.
xcode-select --install. If that does not work, you will need to download Xcode.File > Sync Project with Gradle Files) and they should resolve once the build completes../studiow with a new project set but you're still seeing the old project set in Project, use File > Sync Project with Gradle Files to force a re-sync.repo status to check for any files listed in a “deleted” status. If there are deleted files, navigate to each directory containing these files and run git reset --hard on each of the directories of the deleted files.studio64.vmoptions file using Help > Edit Custom VM Options: -Dsun.java2d.uiScale.enabled=false./studiow main only loads the main set of androidx projects; run ./studiow compose to load the tasks specific to Compose.If in the future you encounter unexpected errors in Studio and you want to check for the possibility it is due to some incorrect settings or other generated files, you can run ./studiow --clean main <project subset> or ./studiow --reinstall <project subset> to clean generated files or reinstall Studio.
@Preview annotation previewsAdd the following dependencies to your project's build.gradle:
dependencies { implementation(project(":compose:ui:ui-tooling-preview")) debugImplementation(project(":compose:ui:ui-tooling")) }
Then, use it like you would on an external project.
Similar to Android framework development, library development should occur in CL-specific working branches. Use repo to create, upload, and abandon local branches. Use git to manage changes within a local branch.
cd path/to/checkout/frameworks/support/ repo start my_branch_name . # make necessary code changes # use git to commit changes repo upload --cbr -t .
The --cbr switch automatically picks the current repo branch for upload. The -t switch sets the Gerrit topic to the branch name, e.g. my-branch-name. You can refer to the Android documentation for a high level overview of this basic workflow.
If you see the following prompt, choose always:
Run hook scripts from https://android.googlesource.com/platform/manifest (yes/always/NO)?
If the upload succeeds, you'll see an output like:
remote: remote: New Changes: remote: https://android-review.googlesource.com/c/platform/frameworks/support/+/720062 Further README updates remote:
To edit your change, use git commit --amend, and re-upload.
NOTE If you encounter issues with repo upload, consider running upload with trace enabled, e.g. GIT_DAPPER_TRACE=1 repo --trace upload . --cbr -y. These logs can be helpful for reporting issues to the team that manages our git servers.
NOTE If repo upload or any git command hangs and causes your CPU usage to skyrocket (e.g. your laptop fan sounds like a jet engine), then you may be hitting a rare issue with Git-on-Borg and HTTP/2. You can force git and repo to use HTTP/1.1 with git config --global http.version HTTP/1.1.
repo upload automatically runs ktfmt, which will cause the upload to fail if your code has style errors, which it reports on the command line like so:
[FAILED] ktfmt_hook
[path]/MessageListAdapter.kt:36:69: Missing newline before ")"
To find and fix these errors, you can run ktfmt locally, either in a console window or in the Terminal tool in Android Studio. Running in the Terminal tool is preferable because it will surface links to your source files/lines so you can easily navigate to the code to fix any problems.
First, to run the tool and see all of the errors, run:
./gradlew module:submodule:ktCheck
where module/submodule are the names used to refer to the module you want to check, such as navigation:navigation-common. You can also run ktfmt on the entire project, but that takes longer as it is checking all active modules in your project.
Many of the errors that ktfmt finds can be automatically fixed by running ktFormat:
./gradlew module:submodule:ktFormat
ktFormat will report any remaining errors, but you can also run ktCheck again at any time to see an updated list of the remaining errors.
Gradle :tasks command allows you to find all the useful tasks for a given project. For example, the following command will let you find tasks available for :core:core project:
./gradlew :core:core:tasks
To build a specific module, use the module's assemble Gradle task. For example, if you are working on core module use:
./gradlew core:core:assemble
To make warnings fail your build (same as presubmit), use the --strict flag, which our gradlew expands into a few correctness-related flags including -Pandroidx.validateNoUnrecognizedMessages:
./gradlew core:core:assemble --strict
To generate a local Maven artifact for the specific module and place it in out/repository, use the publish Gradle task:
./gradlew core:core:publish
To build every module and generate the local Maven repository artifacts and place them in out/repository, use the createArchive Gradle task:
./gradlew createArchive
To run the complete build task that our build servers use, use the corresponding shell script:
./busytown/androidx.sh
Gradle tasks, including building a module, may be run or debugged from within Android Studio. To start, you need to add the task as a run configuration: you can do this manually by adding the corresponding task by clicking on the run configuration dropdown, pressing Edit Configurations, and adding the corresponding task.
You can also run the task through the IDE from the terminal, by using the Run highlighted command using IDE feature - type in the task you want to run in the in-IDE terminal, and ctrl+enter / cmd+enter to launch this through the IDE. This will automatically add the configuration to the run configuration menu - you can then cancel the task.
Once the task has been added to the run configuration menu, you can start debugging as with any other task by pressing the debug button.
Note that debugging will not be available until Gradle sync has completed.
Tasks may also be debugged from the command line, which may be useful if ./studiow cannot run due to a Gradle task configuration issue.
./gradlew <your_task_here> -Dorg.gradle.debug=true --no-daemonIf you get a “Connection refused” error, it's likely because a gradle daemon is still running on the port specified in the config, and you can fix this by killing the running gradle daemons:
./gradlew --stop
NOTE This is described in more detail in this Medium article.
Annotation processors run as part of the build, to debug them is similar to debugging the build.
For a Java project:
./gradlew <your_project>:compileDebugJava --no-daemon --rerun-tasks -Dorg.gradle.debug=true
For a Kotlin project:
./gradlew <your_project>:compileDebugKotlin --no-daemon --rerun-tasks -Dorg.gradle.debug=true -Dkotlin.compiler.execution.strategy="in-process" -Dkotlin.daemon.jvm.options="-Xdebug,-Xrunjdwp:transport=dt_socket\,address=5005\,server=y\,suspend=n"
To enable tools such as PSI tree inside of IntelliJ/Studio to help debug Android Lint checks and Metalava, you can enable the internal menu which is typically used for plugin and IDE development.
See Reference documentation for information on building API reference documentation.
Public API tasks -- including tracking, linting, and verifying compatibility -- are run under the following conditions based on the androidx configuration block, evaluated in order:
runApiTasks=Yes => yesrunApiTasks=No => notoolingProject=true => nomavenVersion or group version not set => noapi/ directory => yespublish=SNAPSHOT_AND_RELEASE => yesIf you make changes to tracked public APIs, you will need to acknowledge the changes by updating the <component>/api/current.txt and associated API files. This is handled automatically by the updateApi Gradle task:
# Run updateApi for all modules. ./gradlew updateApi # Run updateApi for a single module, ex. appcompat-resources in group appcompat. ./gradlew :appcompat:appcompat-resources:updateApi
If you change the public APIs without updating the API file, your module will still build but your CL will fail Treehugger presubmit checks.
NOTE The updateApi task does not generate versioned API files (e.g. 1.0.0-beta01.txt) during a library's alpha, rc or stable cycles. The task will always generate current.txt API files.
api/?Historical API surfaces are tracked for compatibility and docs generation purposes. For each version -- including current to represent the tip-of-tree version -- we record three different types of API surfaces.
<version>.txt: Public API surface, tracked for compatibilityrestricted_<version>.txt: @RestrictTo API surface, tracked for compatibility where necessary (see Restricted APIs)public_plus_experimental_<version>.txt: Public API surface plus @RequiresOptIn experimental API surfaces used for documentation (see Experimental APIs) and API reviewNOTE: Experimental API tracking for KLib is enabled by default for KMP projects via parallel updateAbi and checkAbi tasks. If you have a problem with these tools, please file an issue. As a workaround, you may opt-out by setting enableBinaryCompatibilityValidator = false under AndroidxMultiplatformExtension in your library's build.gradle file.
AndroidX libraries are expected to include unit or integration test coverage for 100% of their public API surface. Additionally, all CLs must include a Test: stanza indicating which tests were used to verify correctness. Any CLs implementing bug fixes are expected to include new regression tests specific to the issue being fixed.
Generally, tests in the AndroidX repository should be run through the Android Studio UI. You can also run tests from the command line or via remote devices on FTL, see Running unit and integration tests for details.
@Test method name and select Run <name>Project side panel, open the desired moduleRun <package>The AndroidX repository has a set of Android applications that exercise AndroidX code. These applications can be useful when you want to debug a real running application, or reproduce a problem interactively, before writing test code.
These applications are named either <libraryname>-integration-tests-testapp, or support-\*-demos (e.g. support-v4-demos or support-leanback-demos). You can run them by clicking Run > Run ... and choosing the desired application.
See the Testing page for more resources on writing, running, and monitoring tests.
The Android Studio instance started by ./studiow uses a custom SDK directory, which means any virtual devices created by a “standard” non-AndroidX instance of Android Studio will be visible from the ./studiow instance but will be unable to locate the SDK artifacts -- they will display a Download button.
You can either use the Download button to download an extra copy of the SDK artifacts or you can set up a symlink to your “standard” non-AndroidX SDK directory to expose your existing artifacts to the ./studiow instance:
# Using the default MacOS Android SDK directory... ln -s /Users/$(whoami)/Library/Android/sdk/system-images \ ../../prebuilts/fullsdk-darwin/system-images
See Library snapshots for information on using snapshot builds.
See FAQ for answers to frequently asked questions.