package lwt

  1. Overview
  2. Docs
Promises and event-driven I/O

Install 

dune-project
 Dependency

github.com Readme MIT License Edit opam file Versions (30)

Authors

  1. J
    Jérôme Vouillon
  2. J
    Jérémie Dimino

Maintainers

  1. R
    Raphaël Proust <code@bnwr.net>
  2. Anton Bachin

Sources

6.0.0-alpha00.tar.gz
md5=8a88c5d5fcb01d179bbb12e6b6888dca
sha512=bfecd3fa0a3461a3368bd7724e2fce7a751ba3899d590d5b08bc4257b058ca34ec25de1a3ead6585528afe77c6ca6db1c3e2d2421d6a773c845ef091472d2ed9

Description

A promise is a value that may become determined in the future.

Lwt provides typed, composable promises. Promises that are resolved by I/O are resolved by Lwt in parallel.

Meanwhile, OCaml code, including code creating and waiting on promises, runs in a single thread by default. This reduces the need for locks or other synchronization primitives. Code can be run in parallel on an opt-in basis.

Published: 24 Jul 2025

README

Lwt

version GitHub Actions status

Lwt is a concurrent programming library for OCaml. It provides a single data type: the promise, which is a value that will become determined in the future. Creating a promise spawns a computation. When that computation is I/O, Lwt runs it in parallel with your OCaml code.

OCaml code, including creating and waiting on promises, is run in a single thread by default, so you don't have to worry about locking or preemption. You can detach code to be run in separate threads on an opt-in basis.

Here is a simplistic Lwt program which requests the Google front page, and fails if the request is not completed in five seconds:

open Lwt.Syntax

let () =
  let request =
    let* addresses = Lwt_unix.getaddrinfo "google.com" "80" [] in
    let google = Lwt_unix.((List.hd addresses).ai_addr) in

    Lwt_io.(with_connection google (fun (incoming, outgoing) ->
      let* () = write outgoing "GET / HTTP/1.1\r\n" in
      let* () = write outgoing "Connection: close\r\n\r\n" in
      let* response = read incoming in
      Lwt.return (Some response)))
  in

  let timeout =
    let* () = Lwt_unix.sleep 5. in
    Lwt.return None
  in

  match Lwt_main.run (Lwt.pick [request; timeout]) with
  | Some response -> print_string response
  | None -> prerr_endline "Request timed out"; exit 1

(* ocamlfind opt -package lwt.unix -linkpkg example.ml && ./a.out *)

In the program, functions such as Lwt_io.write create promises. The let* ... in construct is used to wait for a promise to become determined; the code after in is scheduled to run in a "callback." Lwt.pick races promises against each other, and behaves as the first one to complete. Lwt_main.run forces the whole promise-computation network to be executed. All the visible OCaml code is run in a single thread, but Lwt internally uses a combination of worker threads and non-blocking file descriptors to resolve in parallel the promises that do I/O.


Overview

Lwt compiles to native code on Linux, macOS, Windows, and other systems. It's also routinely compiled to JavaScript for the front end and Node by js_of_ocaml.

In Lwt,

  • The core library Lwt provides promises...
  • ...and a few pure-OCaml helpers, such as promise-friendly mutexes, condition variables, and mvars.
  • There is a big Unix binding, Lwt_unix that binds almost every Unix system call. A higher-level module Lwt_io provides nice I/O channels.
  • Lwt_process is for subprocess handling.
  • Lwt_preemptive spawns system threads.
  • The PPX syntax allows using all of the above without going crazy!
  • There are also some other helpers, such as Lwt_react for reactive programming. See the table of contents on the linked manual pages!

Installing

  1. Use your system package manager to install a development libev package. It is often called libev-dev or libev-devel.
  2. opam install conf-libev lwt

Documentation

We are currently working on improving the Lwt documentation (drastically; we are rewriting the manual). In the meantime:

  • The current manual can be found here.
  • Mirage has a nicely-written Lwt tutorial.
  • An example of a simple server written in Lwt.
  • Concurrent Programming with Lwt is a nice source of Lwt examples. They are translations of code from the excellent Real World OCaml, but are just as useful if you are not reading the book.

Note: much of the current manual refers to 'a Lwt.t as "lightweight threads" or just "threads." This will be fixed in the new manual. 'a Lwt.t is a promise, and has nothing to do with system or preemptive threads.


Contact

Open an issue, visit Discord chat, ask on discuss.ocaml.org, or on Stack Overflow.

Release announcements are made on discuss.ocaml.org. Watching the repo for "Releases only" is also an option.


Contributing

  • CONTRIBUTING.md contains tips for working on the code, such as how to check the code out, how review works, etc. There is also a high-level outline of the code base.
  • Ask us anything, whether it's about working on Lwt, or any question at all about it :)
  • The documentation always needs proofreading and fixes.
  • You are welcome to pick up any other issue, review a PR, add your opinion, etc.
  • Any feedback is welcome, including how to make contributing easier!

Libraries to use with Lwt

Dependencies (5)

  1. ocplib-endian
  2. dune-configurator
  3. cppo build & >= "1.1.0"
  4. ocaml >= "4.08"
  5. dune >= "2.7"

Dev Dependencies (3)

  1. bisect_ppx with-test
  2. odoc with-doc & >= "2.3.0"
  3. ocamlfind with-dev-setup & >= "1.7.3-1"

  1. 0install >= "2.15.1"
  2. aches-lwt
  3. activitypub
  4. albatross
  5. alcotest-lwt
  6. alcotest-mirage
  7. ambient-context-lwt
  8. amqp-client >= "1.1.0"
  9. amqp-client-lwt
  10. angstrom-lwt-unix >= "0.11.0"
  11. anthill
  12. anycache-lwt
  13. archi-lwt
  14. arp
  15. awa-mirage
  16. aws-lwt
  17. aws-s3-lwt < "4.4.0" | >= "4.8.1"
  18. awsm-lwt
  19. azure-cosmos-db
  20. balancer
  21. bastet_lwt
  22. bistro
  23. brisk-reconciler
  24. brozip
  25. builder
  26. builder-web
  27. bun >= "0.3.3"
  28. cachet-lwt
  29. calculon
  30. caldav
  31. camltc
  32. canary
  33. capnp-rpc-lwt < "2.0"
  34. capnp-rpc-unix < "2.1"
  35. caqti-mirage
  36. carton < "1.0.0"
  37. carton-git
  38. carton-lwt
  39. catala-format >= "0.2.0"
  40. cf-lwt
  41. chamelon
  42. chamelon-unix
  43. chamo
  44. charrua-client
  45. charrua-unix
  46. chess_com_api
  47. clz
  48. cmdtui-lambda-term
  49. coap
  50. coap-server-lwt
  51. cohttp-curl-lwt
  52. cohttp-lwt
  53. cohttp-lwt-jsoo
  54. cohttp-lwt-unix
  55. cohttp-mirage
  56. cohttp-server-lwt-unix
  57. comby
  58. comby-semantic
  59. conan-lwt
  60. conduit-lwt
  61. conduit-lwt-unix
  62. cowabloga
  63. crunch
  64. cstruct-lwt
  65. csv-lwt
  66. ctypes >= "0.15.0" & < "0.21.1"
  67. ctypes-foreign >= "0.21.1"
  68. current
  69. current-albatross-deployer
  70. current_docker
  71. current_examples
  72. current_git
  73. current_github
  74. current_gitlab
  75. current_ocluster
  76. current_rpc
  77. current_slack
  78. current_web
  79. DkSDKFFIOCaml_Std
  80. dap
  81. data-encoding < "0.1.1"
  82. devkit >= "1.2"
  83. distributed-lwt
  84. dkim-bin < "0.8.0"
  85. dkim-lwt-unix
  86. dkim-mirage
  87. dlm
  88. dmarc
  89. dns-certify
  90. dns-cli
  91. dns-client < "7.0.3"
  92. dns-client-lwt
  93. dns-client-mirage
  94. dns-forward
  95. dns-forward-lwt-unix
  96. dns-lwt
  97. dns-mirage
  98. dns-resolver
  99. dns-server
  100. dns-stub
  101. dnssd
  102. docker_hub
  103. docteur >= "0.0.2"
  104. docteur-solo5
  105. docteur-unix >= "0.0.5"
  106. doi2bib
  107. dream
  108. dream-httpaf
  109. dream-pure
  110. dream-serve
  111. dropbox
  112. dune >= "3.17.2"
  113. dune-rpc-lwt
  114. earlybird
  115. elasticsearch-cli
  116. emoji = "2.0.0"
  117. equinoxe
  118. ethernet
  119. ez_api >= "1.2.0"
  120. ezcurl-lwt
  121. ezjs_min < "0.2"
  122. ezjsonm-lwt
  123. ezresto
  124. ezresto-directory >= "0.5"
  125. faraday-lwt
  126. faraday-lwt-unix
  127. fat-filesystem
  128. fiber-lwt
  129. fsevents-lwt
  130. fswatch_lwt
  131. gdbprofiler
  132. git
  133. git-cohttp
  134. git-cohttp-unix
  135. git-kv >= "0.2.0"
  136. git-mirage
  137. git-paf
  138. git-unix >= "3.2.0"
  139. github
  140. github-hooks
  141. github-unix >= "4.4.0"
  142. gitlab-unix
  143. gitlab_pipeline_notifier
  144. gluten-lwt
  145. gluten-lwt-unix < "0.4.0"
  146. gluten-mirage < "0.4.0"
  147. graphql-lwt
  148. gremlin
  149. grpc-lwt
  150. guardian
  151. gufo
  152. h1
  153. h1-lwt-unix
  154. h2-lwt
  155. h2-lwt-unix < "0.10.0"
  156. h2-mirage
  157. happy-eyeballs-lwt
  158. happy-eyeballs-mirage
  159. hidapi-lwt
  160. hiredis >= "0.6"
  161. hl_yaml
  162. hockmd
  163. http-lwt-client
  164. http-mirage-client
  165. http-multipart-formdata >= "2.0.0" & < "3.0.0"
  166. httpaf-lwt-unix
  167. httpun-lwt
  168. httpun-mirage
  169. httpun-ws-lwt
  170. hvsock
  171. i3ipc
  172. influxdb-lwt
  173. inotify >= "2.4"
  174. inquire < "0.3.0"
  175. interface-prime-lwt
  176. ip2location
  177. ip2locationio
  178. ip2whois
  179. ipv6-multicast-lwt
  180. irc-client-lwt
  181. irc-client-lwt-ssl
  182. irc-client-tls
  183. irmin
  184. irmin-bench
  185. irmin-chunk
  186. irmin-cli
  187. irmin-client
  188. irmin-containers
  189. irmin-fs
  190. irmin-git
  191. irmin-graphql
  192. irmin-http
  193. irmin-indexeddb
  194. irmin-layers
  195. irmin-mirage-git
  196. irmin-mirage-graphql
  197. irmin-pack
  198. irmin-server
  199. irmin-test
  200. irmin-unix
  201. irmin-watcher
  202. joolog
  203. jose < "0.9.0"
  204. js_of_ocaml-lwt >= "3.5.0"
  205. jsoo_broadcastchannel
  206. jsoo_storage
  207. jupyter
  208. jupyter-kernel
  209. kafka < "0.5"
  210. kafka_lwt
  211. kappa-library
  212. ke >= "0.5"
  213. kinetic-client
  214. kubecaml
  215. lambda-runtime
  216. lambda-term >= "3.3.3"
  217. lambda_streams_lwt
  218. launchd
  219. ldp
  220. learn-ocaml
  221. learn-ocaml-client
  222. ledgerwallet >= "0.4.0"
  223. letsencrypt
  224. letsencrypt-app
  225. letsencrypt-dns
  226. letters
  227. lichess_api
  228. links >= "0.9.1"
  229. llama
  230. lru_cache
  231. lwt-canceler
  232. lwt-dllist
  233. lwt-exit
  234. lwt-parallel
  235. lwt-pipe
  236. lwt-pipeline
  237. lwt-watcher
  238. lwt_camlp4
  239. lwt_direct != "6.0.0~beta01"
  240. lwt_ppx >= "6.0.0"
  241. lwt_react
  242. lwt_retry
  243. lwt_ssl
  244. mariadb >= "1.2.0"
  245. markdown_monolith
  246. markup = "0.7.6"
  247. markup-lwt
  248. mdx
  249. mechaml
  250. mehari-lwt-unix
  251. mehari-mirage
  252. memtrace-mirage
  253. metrics-influx
  254. metrics-lwt
  255. metrics-unix
  256. mimic
  257. mindstorm-lwt
  258. mirage < "4.0.0"
  259. mirage-block >= "2.0.1"
  260. mirage-block-ccm
  261. mirage-block-combinators
  262. mirage-block-lwt
  263. mirage-block-partition
  264. mirage-block-ramdisk
  265. mirage-block-solo5
  266. mirage-block-unikraft
  267. mirage-block-unix >= "2.14.2"
  268. mirage-block-xen
  269. mirage-channel >= "4.0.1"
  270. mirage-channel-lwt
  271. mirage-clock-lwt
  272. mirage-clock-unix < "4.2.0"
  273. mirage-console-lwt
  274. mirage-crypto-rng < "0.11.3"
  275. mirage-crypto-rng-lwt
  276. mirage-crypto-rng-mirage
  277. mirage-device >= "2.0.0"
  278. mirage-flow >= "3.0.0"
  279. mirage-flow-combinators
  280. mirage-flow-lwt
  281. mirage-flow-unix
  282. mirage-fs >= "4.0.0"
  283. mirage-fs-lwt
  284. mirage-kv >= "3.0.1"
  285. mirage-kv-lwt
  286. mirage-kv-unix
  287. mirage-net >= "4.0.0"
  288. mirage-net-lwt
  289. mirage-net-macosx
  290. mirage-net-solo5
  291. mirage-net-unikraft
  292. mirage-net-unix
  293. mirage-net-xen
  294. mirage-profile
  295. mirage-protocols >= "7.0.0"
  296. mirage-protocols-lwt
  297. mirage-qubes
  298. mirage-qubes-ipv4
  299. mirage-runtime
  300. mirage-sleep
  301. mirage-solo5
  302. mirage-stack = "3.0.0"
  303. mirage-stack-lwt
  304. mirage-time >= "3.0.0"
  305. mirage-time-lwt
  306. mirage-time-unix
  307. mirage-types-lwt
  308. mirage-unikraft
  309. mirage-unix
  310. mirage-vnetif
  311. mirage-xen
  312. monorobot
  313. mqtt
  314. mrmime >= "0.5.0"
  315. multipart-form-data
  316. multipart_form >= "0.2.0" & < "0.4.0"
  317. multipart_form-cohttp-lwt < "0.6.0"
  318. multipart_form-lwt
  319. naboris
  320. nbd >= "4.0.3"
  321. nbd-tool
  322. nbd-unix
  323. neo4j_bolt
  324. nottui-lwt
  325. notty-community
  326. nproc
  327. nsq
  328. obuilder
  329. obus >= "1.2.1"
  330. ocluster-api
  331. ocluster-worker
  332. ocplib-resto
  333. ocsigenserver
  334. ocsipersist
  335. ocsipersist-dbm
  336. ocsipersist-lib
  337. ocsipersist-pgsql
  338. ocsipersist-sqlite
  339. octez-distributed-lwt-internal
  340. octez-internal-libs
  341. octez-l2-libs
  342. octez-libs
  343. octez-proto-libs
  344. octez-protocol-compiler
  345. octez-proxy-server
  346. octez-rpc-process
  347. octez-shell-libs
  348. octez-smart-rollup-wasm-benchmark-lib
  349. oframl
  350. ojs_base
  351. omigrate
  352. oneffs
  353. opam-check-npm-deps >= "4.1.0"
  354. opencage
  355. opentelemetry-client-cohttp-lwt
  356. opentelemetry-cohttp-lwt >= "0.4"
  357. opentelemetry-lwt
  358. opium
  359. opium-graphql
  360. opium_kernel
  361. opomodoro
  362. order-i3-xfce
  363. ordma
  364. oskel >= "0.3.0"
  365. ounit-lwt < "2.2.0"
  366. ounit2-lwt
  367. owork
  368. ozulip
  369. paf
  370. paf-cohttp
  371. passage < "0.1.8"
  372. pcap-format < "0.5.2"
  373. petrol
  374. pgn_parser
  375. pgx_lwt
  376. pgx_lwt_mirage
  377. pgx_lwt_unix < "2.0"
  378. piaf < "0.2.0"
  379. picos_meta
  380. plebeia >= "2.0.0"
  381. plotkicadsch
  382. ppx_defer >= "0.4.0"
  383. ppx_deriving_rpc
  384. ppx_rapper_lwt
  385. proc-smaps
  386. prof_spacetime
  387. prometheus
  388. prometheus-app
  389. promise_jsoo_lwt
  390. protocol-9p
  391. protocol-9p-unix
  392. proton
  393. pxshot
  394. qcow
  395. qcow-stream
  396. qcow-tool
  397. qcow-types
  398. qdrant < "0.2.0"
  399. qfs >= "0.5"
  400. quests
  401. rawlink < "2.1"
  402. rawlink-lwt
  403. rdf_json_ld
  404. rdf_lwt
  405. redis-lwt
  406. reparse-lwt
  407. reparse-lwt-unix
  408. resource-pooling
  409. resp
  410. resp-mirage >= "0.10.0"
  411. resp-unix >= "0.10.0"
  412. resto
  413. resto-cohttp-client >= "0.4"
  414. resto-cohttp-self-serving-client
  415. resto-cohttp-server >= "0.4" & < "0.6" | >= "0.9"
  416. resto-directory >= "0.4"
  417. riak
  418. ringo-lwt
  419. river
  420. rock
  421. rpclib-js
  422. rpclib-lwt
  423. SZXX < "4.0.0"
  424. sanddb
  425. scgi
  426. sendmail-lwt
  427. sendmail-mirage
  428. serial
  429. server-reason-react
  430. session-cohttp-lwt
  431. session-cookie-lwt
  432. session-postgresql-lwt
  433. sessions
  434. shared-block-ring
  435. shared-memory-ring-lwt
  436. sherlodoc
  437. sihl < "0.2.0"
  438. slack
  439. slacko
  440. slipshow
  441. smtml >= "0.7.0"
  442. speed
  443. spin < "0.8.0"
  444. spoke
  445. statocaml
  446. stk
  447. stog
  448. swapfs
  449. syguslib-utils
  450. syndic >= "1.4" & < "1.6.0"
  451. tar-mirage
  452. tar-unix
  453. tcpip
  454. telegraml
  455. terminus
  456. testo-lwt
  457. tezos-base >= "16.0"
  458. tezos-clic >= "16.0"
  459. tezos-crypto >= "16.0"
  460. tezos-crypto-dal
  461. tezos-error-monad >= "16.0"
  462. tezos-lwt-result-stdlib
  463. tezos-p2p = "12.3"
  464. tezos-protocol-environment
  465. tezos-proxy >= "17.3"
  466. tezos-stdlib
  467. tezos-stdlib-unix >= "16.0"
  468. tezos-test-helpers >= "12.3"
  469. tezos-webassembly-interpreter-extra
  470. tidy_email
  471. timmy-lwt
  472. tls >= "0.10.6" & < "0.16.0"
  473. tls-lwt
  474. tls-mirage
  475. tube
  476. tuntap
  477. twirp_cohttp_lwt_unix
  478. uring
  479. uspf
  480. uspf-lwt
  481. uspf-mirage
  482. utop
  483. uwt
  484. vchan
  485. vchan-unix
  486. vchan-xen
  487. vercel
  488. vhd-format-lwt
  489. vmnet
  490. vpnkit
  491. vue-jsoo < "0.3"
  492. wayland < "2.0"
  493. webauthn
  494. xen-evtchn
  495. xen-evtchn-unix
  496. xen-gnt
  497. xen-gnt-unix
  498. xenstore
  499. xenstore-tool
  500. xenstore_transport
  501. xlsx2csv
  502. yocaml_git
  503. yocaml_unix < "2.0.0"
  504. zarr-lwt
  505. zmq-lwt >= "5.2.1"

Conflicts

None